Skip to main content

PHP SDK Troubleshooting

Solutions for PHP, Laravel, and WordPress issues. WordPress plugin docs: WordPress Integration.

Installation Issues​

Composer Install Fails​

Use the real Packagist package names (not legacy ops-ai/* coordinates):

# Core / vanilla PHP
composer require toggly/feature-management-php

# Laravel (pulls core)
composer require toggly/laravel

# WordPress plugin (pulls core)
composer require toggly/wordpress

Version Compatibility​

Requirements:

  • PHP 7.4+, through PHP 8.5 (PHP 8.5 is the current tested runtime)
  • Laravel 8.0+ when using toggly/laravel; current packed-package checks cover Laravel 10.3.3, 11.6.1, 12.12.2, and 13.10.1
  • WordPress 5.0+ when using toggly/wordpress; the maintained package is currently validated on WordPress 7.1 with PHP 8.5
# Check PHP version
php --version

# Update composer
composer self-update

Configuration Issues​

App Key Not Found​

Core (vanilla PHP):

use Toggly\FeatureManagement\Config\TogglySettings;

$appKey = getenv('TOGGLY_APP_KEY');
if ($appKey === false || $appKey === '') {
    throw new RuntimeException('TOGGLY_APP_KEY not set');
}

$settings = new TogglySettings([
    'app_key' => $appKey,
    'environment' => getenv('TOGGLY_ENVIRONMENT') ?: 'Production',
]);

Laravel:

php artisan vendor:publish --tag=toggly-config
TOGGLY_APP_KEY=your-key-here
TOGGLY_ENVIRONMENT=Production

Environment names are case sensitive (Production ≠ production).

Laravel-Specific Issues​

Service Provider Not Loaded​

Package auto-discovery registers Toggly\Laravel\ServiceProvider and the Toggly facade. If auto-discovery is disabled, register manually:

// config/app.php
'providers' => [
    Toggly\Laravel\ServiceProvider::class,
],
'aliases' => [
    'Toggly' => Toggly\Laravel\Facades\Toggly::class,
],
php artisan vendor:publish --tag=toggly-config
php artisan config:clear

Facade Not Working​

use Toggly\Laravel\Facades\Toggly;
use Toggly\FeatureManagement\Core\FeatureManager;

if (Toggly::isEnabled('my-feature')) {
    // …
}

// Or inject FeatureManager
public function __construct(private FeatureManager $features) {}

Cache / Config Stale After Install​

php artisan cache:clear
php artisan config:clear
php artisan route:clear

Snapshot / Offline Issues​

Prefer snapshot providers over inventing a custom cache layer:

use Toggly\FeatureManagement\Storage\SnapshotProviders\FileSnapshotProvider;
use Toggly\FeatureManagement\Storage\SnapshotSettings;

$snapshots = new FileSnapshotProvider(
    sys_get_temp_dir() . '/toggly',
    new SnapshotSettings(['document_name' => 'toggly_features'])
);
$featureProvider->setSnapshotProvider($snapshots);

In Laravel, set TOGGLY_SNAPSHOT_PROVIDER=cache|database|file in .env.

See Snapshot Providers.

Performance Tips​

  • Keep a single FeatureManager / provider instance per process (Laravel DI already does this).
  • Use snapshots so cold starts do not depend on the definitions API.
  • In PHP-FPM, live WebSocket updates are skipped automatically; rely on refresh interval + snapshots.
  • Enable OPcache in production (opcache.enable=1).

Authentication Issues​

See General Authentication Guide.

// Wrong — literal env var name
$settings = new TogglySettings(['app_key' => 'TOGGLY_APP_KEY', ...]);

// Correct — actual key value
$settings = new TogglySettings(['app_key' => getenv('TOGGLY_APP_KEY'), ...]);

Error Handling​

Wire on_error on settings for refresh/snapshot failures, and treat evaluation failures as disabled unless you explicitly want fail-open:

$settings = new TogglySettings([
    'app_key' => getenv('TOGGLY_APP_KEY'),
    'environment' => 'Production',
    'on_error' => function (string $message, ?Throwable $e): void {
        error_log('Toggly: ' . $message);
    },
]);

try {
    $enabled = $featureManager->isEnabled('my-feature');
} catch (Throwable $e) {
    error_log('Toggly evaluation error: ' . $e->getMessage());
    $enabled = false;
}

Common Mistakes​

1. Wrong package coordinates​

ops-ai/toggly-php / ops-ai/toggly-laravel are not Packagist packages. Use toggly/feature-management-php, toggly/laravel, and toggly/wordpress.

2. Creating managers in loops​

// Bad — new stack every iteration
foreach ($users as $user) {
    $fm = /* build FeatureManager again */;
}

// Good — reuse one FeatureManager; pass per-call context
foreach ($users as $user) {
    $fm->isEnabled('feature', ['userId' => (string) $user->id]);
}

3. Missing Composer autoload​

require __DIR__ . '/vendor/autoload.php';

4. Expecting \Toggly\Client​

There is no Toggly\Client class. Use FeatureManager (core) or the Laravel Toggly facade / injected FeatureManager.

Debugging​

Log refresh failures via on_error, inspect Laravel config, and confirm Packagist versions:

composer show toggly/feature-management-php
composer show toggly/laravel   # if applicable

Getting More Help​