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​

The examples use PHP 8 syntax. 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

Package metadata alone does not establish compatibility with every older PHP or framework release. Check your installed platform:

# Check PHP version
php --version

# Update composer
composer check-platform-reqs

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 Toggly\Laravel\ServiceProvider::class in bootstrap/providers.php for current Laravel applications. Older applications with a config/app.php provider list can use:

// 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

PSR interface cannot be resolved​

Register Psr\Http\Client\ClientInterface and Psr\Http\Message\RequestFactoryInterface in your application provider, then refresh before the first check. See host bootstrap.

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 = new \Toggly\FeatureManagement\Core\FeatureProvider(
    $settings, $http, $state, $snapshots
);
$featureProvider->refreshFeatures();

The other constructor dependencies come from the core setup. In Laravel, choose cache, database or file for TOGGLY_SNAPSHOT_PROVIDER in .env.

See Snapshot Providers.

Performance Tips​

  • Reuse ordinary definitions within a process; keep targeting, authorization and telemetry context request-local. Laravel persistent workers require the lifecycle qualification.
  • Use snapshots so cold starts do not depend on the definitions API.
  • In PHP-FPM, live WebSocket updates are skipped. Schedule explicit refreshes of shared snapshots; refresh_interval does not start a timer.
  • Enable OPcache in production (opcache.enable=1).

Authentication Issues​

See General Authentication Guide.

Read the value with getenv('TOGGLY_APP_KEY'); do not pass the literal string TOGGLY_APP_KEY as your app key. Validate that it is nonempty before startup.

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​

Reuse the initialized manager for ordinary checks and pass the current identity on each call. Do not change a shared provider's identity for variants; give variants a provider with the correct initial identity and isolated persistence.

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​