Plugins

A plugin groups reusable setup in one place: macros, type registries, query pipes, hook callbacks, default configuration and package integration. It is the supported way for an application or a companion package to change what the framework does — and the first question on this page is whether you need one at all, because a closure, an event or a macro is often the smaller answer.

For a single table, form, or action, prefer the public fluent API first. Use a plugin when the same behavior should be installed once and reused across multiple components, projects, or packages.

When To Use A Plugin

Hook, Event, Macro Or Callback

Four ways to change behaviour exist in this stack, and the one to reach for is decided by a single question: who holds the reference to the component?

Where both a hook and an event exist for one moment — action.executing and ActionExecuting fire ten lines apart — the event is the observation half. Audit trails, telemetry and metrics belong there; changing what runs belongs in the hook.

The practical case for the third row is a module installed from a package: its list is built inside code the application does not own, so a column is added by a table.composing hook rather than by subclassing the resource — which would collide on its key anyway.

What A Plugin Can Do

Quick Start

Create a plugin class:

<?php
 
namespace App\Wire\Plugins;
 
use Illuminate\Database\Eloquent\Builder;
use NyonCode\WireCore\Core\Plugin\Contracts\Plugin;
use NyonCode\WireCore\Core\Plugin\PluginManager;
use NyonCode\WireTable\Table;
 
final class TenantPlugin implements Plugin
{
    public function getId(): string
    {
        return 'tenant';
    }
 
    public function register(PluginManager $manager): void
    {
        //
    }
 
    public function boot(PluginManager $manager): void
    {
        Table::macro('tenantScoped', function (?int $tenantId = null): static {
            $tenantId ??= auth()->user()?->tenant_id;
 
            return $this->modifyQueryUsing(
                fn (Builder $query) => $query->where('tenant_id', $tenantId)
            );
        });
    }
}

Register it in config/wire-core.php:

'plugins' => [
    App\Wire\Plugins\TenantPlugin::class,
],

Use the macro from any table:

public function table(Table $table): Table
{
    return $table
        ->model(Order::class)
        ->tenantScoped()
        ->columns([
            // ...
        ]);
}

Plugin Contract

Every plugin implements NyonCode\WireCore\Core\Plugin\Contracts\Plugin.

<?php
 
namespace App\Wire\Plugins;
 
use NyonCode\WireCore\Core\Plugin\Contracts\Plugin;
use NyonCode\WireCore\Core\Plugin\PluginManager;
 
final class ExamplePlugin implements Plugin
{
    public function getId(): string
    {
        return 'example';
    }
 
    public function register(PluginManager $manager): void
    {
        // Register hooks, query pipes, type aliases, or lightweight metadata.
    }
 
    public function boot(PluginManager $manager): void
    {
        // Register macros or resolve services after all plugins are registered.
    }
}

The getId() value must be unique. Registering two plugins with the same ID throws a RuntimeException.

Lifecycle

PluginManager::register() calls the plugin's register() method immediately. PluginManager::boot() runs each plugin's boot() method once, and closes registration: a plugin offered afterwards is refused rather than accepted into a list nothing reads again.

Keep register() lightweight. Do not resolve request-scoped services or assume every Laravel service has already booted. Use boot() for work that needs the container, views, macros, or other registered plugins.

PluginManager API

Best Practices

• Use stable, lowercase plugin IDs such as tenant, audit-export, or acme-billing.
• Keep register() lightweight; do not resolve request-scoped services there.
• Put Laravel macros and service-dependent setup in boot().
• Prefer table/form/action fluent APIs for one-off behavior.
• Return a payload array from array hook callbacks when you want to modify hook data.
• Use hook priorities sparingly and document why a callback must run early or late.
• Guard package registration with PluginManager::has() to avoid duplicate IDs.
• Treat type registries as metadata unless your package explicitly consumes them.

In This Section

Related

• Modules — a business area declared as a plugin
• Foundation — the concerns a plugin registers into
• Configuration — where plugins is declared
• Custom Fields — the other extension path, for one component