SIGNALS Docs
Exit Reader View
100%
Theme

Plugin data tables

Plugin-owned database tables, migrations, Eloquent models and uninstall behaviour.

Declare and migrate plugin tables

Declare owned tables in signals.yaml and place migrations under the package's database/migrations/ directory. Table names must match plugin_[a-z][a-z0-9_]*. Include your vendor and package identity to avoid collisions.

tables:
  - plugin_acme_reviews

Install and update call PluginMigrationGuard::run() with that directory. It snapshots table names before and after the migration batch, rejects newly created non-plugin_ tables and removed core tables, and rolls back the rejected batch before throwing. It does not compare column changes, enforce ownership between two plugins' tables, or sandbox arbitrary PHP or SQL. Do not alter or seed core tables from plugin migrations.

Use the default connection. The guard inspects Schema's default connection; switching to another connection escapes that inspection and is not a supported plugin migration pattern.

Eloquent models

Use the package's Composer PSR-4 namespace under src/ and explicitly name the table:

namespace Acme\Review\Models;

use Illuminate\Database\Eloquent\Model;

final class Review extends Model
{
    protected $table = 'plugin_acme_reviews';

    protected $fillable = ['external_reference', 'status'];
}

Leave the model's connection unset so it follows the active tenant connection. For your own tests, create factories for your plugin models and seed only your own tables. Core entity reads and writes belong behind the context data API, with declared access.

Cloud and uninstall

Cloud's TenantConnection establishes a database per tenant. Plugin lifecycle operations and their migrations run against the active tenant database; PluginLifecycleManager does not iterate every tenant. Deployment tooling must perform the install or update for each intended tenant. Queue dispatch must originate in the intended tenant context so the worker can restore it.

Uninstall invokes the plugin's uninstall() hook, removes its settings, permissions, notification types and communication templates, then calls PluginMigrationGuard::rollbackAll() if the package is discoverable. This resets migrations from the package path: tables disappear through each migration's down() method, not by blindly dropping every name in tables[]. If the package cannot be discovered, no migration path is reset. Keep package code available until uninstall finishes, and implement reversible migrations for owned tables.