How the TruCMS Plugin System Works

In TruCMS a plugin is a Laravel module that the in-house Plugin Manager can install, activate, deactivate and delete. Booking, TruCommerce, TruPayments and the four payment gateways are built exactly this way, so everything they do, your plugin can do.

In the user guide: the Plugins chapter.

Module or plugin?

They are the same thing seen from two sides:

• Module — the code unit. A folder Modules/{Name} with a module.json, managed by nwidart/laravel-modules (v13). Whether it is loaded is a boolean in modules_statuses.json.
• Plugin — the same folder as an administrator experiences it in Appearance → Plugins: installable from a ZIP, with dependency checks, a protected flag and safe deletion (App\Services\Plugins\*).

Anatomy of a request that involves a plugin

php-fpm starts the app
  bootstrap/providers.php
    ... AppServiceProvider, DotartisanServiceProvider, WidgetsServiceProvider
    LaravelModulesServiceProvider
        reads modules_statuses.json, takes every module that is "true"
        for each, in "priority" order, registers the providers named in module.json
            YourServiceProvider::register()    bindings, config merge
    (all providers registered)
    YourServiceProvider::boot()                views, translations, migrations, routes (child provider),
                                               breadcrumbs, dashboard rows, shortcodes, widgets,
                                               Event::listen(AdminBooting::class, ...)
    $app->booted(...)                          WidgetsServiceProvider loads saved widget instances
                                               FrontendRoutingServiceProvider adds the catch-all slug route

an ADMIN request additionally runs:
  AdminTheme middleware -> core menu + settings registered -> event(AdminBooting)
        -> YOUR listener registers sidebar items and settings sections
  -> your controller -> your Blade view inside <x-admin-layout>

An inactive module is simply never registered: no routes, menus, widgets, schedules or listeners. Its tables are left untouched.

The lifecycle in the Plugin Manager

All operations take a cache lock (plugin-management, 120 seconds, config('plugins.lock_seconds')) so two administrators cannot change plugin state at the same time, and failures are reported as PluginOperationException with a translatable message key (lang/en/plugins.php).

Dependency rules

• requires in module.json maps a plugin alias to a Composer version constraint ({"trupayments": "^1.0"}); a plain list of aliases means "any version". The legacy key requirements is still read.
• Installation checks that required plugins are installed; activation also requires them to be active and in range (Composer\Semver\Semver).
• Circular dependencies are detected and block the operation; an unreadable module.json in the graph blocks deactivation and deletion until fixed.
• Protected plugins ("protected": true in the manifest or listed in config/plugins.php → protected: booking, trucommerce, trupayments) can never be deleted from the UI.
• Helper macros exist on the Module facade: requirements($name), requiredBy($name), withRequirements(), paymentModules() (modules with "payments": true).

Upload limits (config/plugins.php)

The validator also rejects: absolute or .. paths, Windows reserved device names, symlinks and special files, duplicate entries (case-insensitively), more than one module.json, a composer.json whose PSR-4 does not map Modules\{Name}\ to app/, and providers that do not exist as files.

What a plugin can do

Everything below is registered from the plugin's service provider; none of it needs a core edit.

Plugin design guidelines

1. Be additive. Never edit app/ to wire your plugin in. If you find you must, a hook is missing — see Known quirks for the places the core is not fully decoupled yet.
2. Gate everything. Parent access {alias} permission on the route group (as TruCommerce and TruPayments do) plus a permission per action.
3. Be cheap when idle. Registrations run on every request. Build field definitions lazily (closures), avoid queries in boot(), and register admin-only things on AdminBooting.
4. Prefix everything with your alias: routes, permissions, settings keys, widget keys, shortcode ids, dashboard item ids, scheduled commands.
5. Leave data behind safely. Deactivation and deletion never drop tables; make re-activation idempotent (migrations guard with Schema::hasTable, seeders use updateOrCreate).
6. Test it like the bundled modules do — see Testing.