Debugging plugins

Find out why a FeatherPanel plugin does not load, a route returns 404 or a page stays empty. Log messages, the validate endpoint, worker restarts and a release checklist.

Where to look

Write your own log lines with the panel logger:

use App\App;

$logger = App::getInstance(true)->getLogger();
$logger->info('myplugin: sync started');
$logger->warning('myplugin: remote API slow');
$logger->error('myplugin: sync failed: ' . $e->getMessage(), false);

error() and critical() also send the message to the panel’s error telemetry unless the second argument is false. debug() only writes when APP_DEBUG is on, which it is not in release builds, so use info() instead.

Developer mode and the debug console

Turn on developer mode (the app_developer_mode setting) in the admin settings. It unlocks:

• Admin > Dev > Plugins: create plugins from templates, edit their manifest and settings, and add migrations, cron jobs, commands and public files with Create file,
• plugin export,
• the validate endpoint,
• the panel debug console: type ##icanhasfeatherpanel in the global search. It has network probes, benchmarks, a log tail for admins, a debug snapshot you can copy, and links to the developer docs and the dev plugin page.

The validate endpoint

GET /api/admin/plugin-manager/{identifier}/validate returns:

Log messages from the plugin loader

The loader checks each folder in storage/addons/ in this order and stops at the first problem:

Errors when installing a package

Uploading or installing an .fpa checks the entry class before anything is copied. The API answers 422 with:

Common problems

A route returns API_ROUTE_NOT_FOUND

• The file is not under Routes/, does not end in .php, or does not return function (RouteCollection $routes).
• The route file threw while loading. Search the log for Failed to load plugin routes.
• The API runs in worker mode and the worker started before you added the file. Click Resync on the plugin page or restart the backend container. Any successful admin change under /api/admin/plugins makes the workers restart.

PHP changes do not show up

In worker mode, which the Docker image uses by default, each worker keeps your classes in memory until it restarts. Click Resync, save a plugin setting, or restart the backend container. To develop without restarts, set FRANKENPHP_WORKER=false on the backend container so every request loads the code again. See Middleware and router hooks.

Frontend/index.js or index.css changes do not show up

The panel joins every plugin’s index.js (and index.css) and caches the result for two minutes, and the browser may keep it for another minute. Wait, then hard reload. Each plugin’s script is wrapped in its own function, so a variable you expect on window must be assigned to window explicitly. If your script uses window.FeatherPanel, wait until it exists, as the Starter template does.

A sidebar page is empty or shows the wrong file

• component is a path inside Frontend/Components/. The panel loads /components/<identifier>/<component>.
• After copying files by hand, click Resync so public/components/<identifier> points at your folder.
• Open the component URL directly in the browser to see the real error.

A cron job never runs

• The class must be App\Addons\<identifier>\Cron\<file name>. The cron log shows Class ... not found otherwise.
• The interval unit must be upper case: 5M, not 5m.
• An earlier PHP Error (not Exception) in any job stops the whole run. Check the cron log for a fatal error.
• Delete storage/caches/cron/<id>.fptj to force the next run.

A setting is always empty

default in conf.yml is only a placeholder in the form. Seed values in pluginInstall() or fall back in code. See Settings.

Checklist before you release

• conf.yml has every required key, a bumped version, and an identifier that matches the folder.
• The validate endpoint reports overall_valid: true.
• The entry class is the only PHP file in the plugin root.
• Route names and paths are prefixed with your identifier.
• Every value from a request reaches SQL through prepared statements.
• Listeners and processEvents() catch their own exceptions.
• Nothing user-specific is kept in static properties.
• Cron classes use App\Addons\<identifier>\Cron and upper-case intervals.
• Migrations use IF NOT EXISTS and table names start with featherpanel_<identifier>_.
• pluginUninstall() removes the tables and settings the plugin created.
• The plugin installs from an .fpa on a clean panel. See Packaging and publishing.

Related

• Plugin FAQ
• Middleware and router hooks
• Cron jobs and CLI commands