Troubleshooting

Common issues when using wpzylos-core.

PluginContext Issues

"Missing required config keys" error

Problem: InvalidArgumentException: Missing required config keys: file, slug...

Cause: Incomplete configuration passed to PluginContext::create().

Fix: Ensure all required keys are provided:

$context = PluginContext::create([
    'file'       => __FILE__,      // Required
    'slug'       => 'my-plugin',   // Required
    'prefix'     => 'myplugin_',   // Required
    'textDomain' => 'my-plugin',   // Required
    'version'    => '1.0.0',       // Required
]);

Paths return wrong directory

Problem: $context->path() returns unexpected path.

Cause: file config points to wrong file (not main plugin file).

Fix: Always pass the main plugin file:

// Bad: Wrong: passing bootstrap file
'file' => __DIR__ . '/bootstrap/app.php',

// Good: Correct: main plugin file
'file' => __DIR__ . '/my-plugin.php',

URLs broken after moving plugin

Problem: $context->url() returns 404 URLs.

Cause: WordPress caches plugin URLs. Move operation didn't clear cache.

Fix: Clear cached baseUrl:

// Clear object cache or deactivate/reactivate plugin
wp_cache_flush();

Application Issues

Services not available in boot()

Problem: Services return null or throw EntryNotFoundException.

Cause: Accessing services before registration completes.

Fix: Check provider loading order. Dependencies must register first:

// config/app.php
'providers' => [
    DatabaseServiceProvider::class,  // Register first
    CacheServiceProvider::class,     // Depends on database
    AppServiceProvider::class,       // Uses both
],

Multiple boot() calls

Problem: Services initialized multiple times.

Cause: $app->boot() called more than once.

Fix: Boot only once, typically in main plugin file:

// my-plugin.php
add_action('plugins_loaded', function () use ($app) {
    $app->boot(); // Only here
}, 10);

ServiceProvider Issues

Container not available in register()

Problem: $this->container() returns null in register().

Cause: Container accessed before Application sets it.

Fix: Use the container from method parameter:

public function register(ApplicationInterface $app): void
{
    // Good: Use app's container
    $app->container()->singleton(MyService::class);

    // Bad: Don't use $this->container() in register
}

Boot runs before all providers registered

Problem: Provider's boot() can't find services from other providers.

Cause: Incorrect provider priority or early boot call.

Fix: Ensure all providers are registered before boot:

// Register all first
foreach ($providers as $provider) {
    $app->register($provider);
}

// Then boot
$app->boot();

PHP-Scoper Issues

ContextInterface not found after scoping

Problem: Class WPZylos\Framework\Core\Contracts\ContextInterface not found

Cause: PHP-Scoper prefixed the interface but your code references the original namespace.

Fix: Exclude WPZylos interfaces from scoping in scoper.inc.php:

return [
    'exclude-namespaces' => [
        'WPZylos\Framework\Core\Contracts',
    ],
];

Plugin identity lost after build

Problem: Built plugin shows wrong slug/prefix.

Cause: Context was hardcoded instead of using ContextInterface.

Fix: Always depend on ContextInterface, never hardcode identity:

// Bad: Hardcoded
$hook = 'myplugin_custom_event';

// Good: Dynamic from context
$hook = $context->hook('custom_event');
Previous page
Security Notes
Next page
WPZylos Database