Troubleshooting

Scaffold package issues and fixes.

Installation Issues

Composer create-project fails

Problem: create-project fails with dependency error.

Cause: PHP version or missing extensions.

Fix: Check PHP requirements:

php -v  # Must be 8.0+
php -m | grep json  # json extension required

"Directory not empty"

Problem: Can't create project in existing directory.

Cause: Target directory has files.

Fix: Use empty directory or remove first:

rm -rf my-plugin
composer create-project MyCompanystudio/wpzylos-scaffold my-plugin

Structure Issues

Missing directories

Problem: Expected directories not created.

Cause: Scaffold template incomplete.

Fix: Create manually:

mkdir -p app/Http/Controllers
mkdir -p app/Services
mkdir -p resources/views
mkdir -p database/migrations

Namespace mismatched

Problem: Autoloader can't find classes.

Cause: Namespace doesn't match composer.json.

Fix: Verify PSR-4 config:

{
  "autoload": {
    "psr-4": {
      "YourPlugin\\": "app/"
    }
  }
}

Then: composer dump-autoload

Build Issues

PHP-Scoper errors

Problem: Scoper fails with parse errors.

Cause: Incompatible PHP syntax or missing config.

Fix: Check scoper.inc.php:

return [
    'prefix' => 'YourPluginVendor',
    'exclude-namespaces' => [
        'YourPlugin',
    ],
];

Built plugin crashes

Problem: Scoped plugin throws class not found.

Cause: WordPress symbols not excluded.

Fix: Add to scoper exclusions:

'exclude-functions' => [
    'add_action', 'add_filter', 'get_option',
    // ... all WordPress functions
],

Makefile errors on Windows

Problem: make command not found or errors.

Cause: Windows doesn't have make by default.

Fix: Install make via:

Chocolatey: choco install make
Git Bash: Use Git Bash terminal
Or run commands manually from Makefile

Runtime Issues

Plugin doesn't appear in admin

Problem: Plugin activates but no menu appears.

Cause: Service provider not registering menu.

Fix: Check your provider's boot() method:

public function boot(): void
{
    add_action('admin_menu', [$this, 'registerMenus']);
}

PluginContext errors

Problem: "Missing required config keys" error.

Cause: Incomplete context configuration.

Fix: Ensure all required keys are provided:

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

Routes not working

Problem: Custom routes return 404.

Cause: Rewrite rules not flushed.

Fix: Flush rewrite rules:

wp rewrite flush

Or deactivate and reactivate the plugin.

Database Issues

Migration not running

Problem: Tables not created after activation.

Cause: Migrations not triggered.

Fix: Run migrations manually:

wp zylos migrate

Or uncomment migration call in app/Lifecycle/Activator.php.

Table prefix wrong

Problem: Tables created with wrong prefix.

Cause: Incorrect prefix in PluginContext.

Fix: Check the prefix value doesn't include wp_:

'prefix' => 'yourplugin_', // Correct (wp_ added automatically)
'prefix' => 'wp_yourplugin_', // Wrong (will be wp_wp_yourplugin_)

Security Notes

Scaffold CLI Reference