Web plugin tutorial

Build a web plugin#

Start with a clean local VoltexaHub install: run composer install, copy .env.example to .env, configure a disposable local database, run php artisan key:generate, then php artisan forum:install [email protected]. Set FORUM_ADMIN_PASSWORD in the process environment or enter a password at the prompt. Run npm ci && npm run build. Never commit .env, database files or generated accounts.

1. Run php artisan forum:make-plugin hello-board. It creates plugins/hello-board/plugin.json, Plugin.php, and two escaped Blade views. The class namespace includes a stable ID hash so similar IDs cannot collide. The command refuses an existing directory. Do not patch core files.
2. Run php artisan forum:plugin install hello-board, then php artisan forum:plugin enable hello-board (or use Administration → Plugins). The home page shows the example forum.top notice. Its example route is /extensions/hello-board/example; it and the navigation link are hidden until permission is granted.
3. In Administration → Permissions, allow hello-board.view globally for the desired group. Sign in as a member of that group, then open the navigation link and route. Verify a guest or ungranted member receives 403. Any additional handler that reads or writes records must check that object's authorization; the declared global ability alone is insufficient.
4. Add dependencies to requires as an ID-to-constraint object, such as {"base-plugin":"^1.2.0"}. Install dependencies first and enable them first. Use stable major.minor.patch versions; see the constraint grammar. Add migrations under database/migrations/ with globally unique filenames. Declare only plugin-owned tables under owned_tables using the plugin_hello_board prefix. Migrations must be safe to retry after partial DDL failure.
5. For an updated package, raise its manifest version and run php artisan forum:plugin upgrade hello-board. Disable enabled dependents first. If migration fails, inspect the database and repair/retry; the installed version remains old and the plugin stays disabled. Never edit a migration already released to users—ship a corrective migration.
6. Run php artisan forum:plugin disable hello-board to remove public hooks/routes/navigation while retaining data. Run php artisan forum:plugin uninstall hello-board to remove registration but retain tables and migration history. Reinstall the same or a newer compatible package to reuse that data; keep all published migration files in the package so an eventual purge can identify its exact ledger rows. Only an explicit --purge uninstall drops declared tables and exact plugin migration records; back up data first. php artisan forum:plugins:disable or FORUM_PLUGINS_ENABLED=false recovers a public site from a faulty plugin boot without requiring that plugin to run in Administration.

Package only the plugins/hello-board directory. Plugin code is trusted PHP; review it before installation. Unsupported CLI and queued-listener registration are outside the web extension contract.