Download the PHP package calebdw/laravel-sql-entities without Composer

Laravel's schema builder and migration system are great for managing tables and indexes---but offer no built-in support for other SQL entities, such as (materialized) views, procedures, functions, and triggers. These often get handled via raw SQL in migrations, making them hard to manage, prone to unknown conflicts, and difficult to track over time.

laravel-sql-entities solves this by offering:

• 📦 Class-based definitions: bringing views, functions, triggers, and more into your application code.
• 🧠 First-class source control: you can easily track changes, review diffs, and resolve conflicts.
• 🧱 Decoupled grammars: letting you support multiple drivers without needing dialect-specific SQL.
• 🔁 Lifecycle hooks: run logic at various points, enabling logging, auditing, and more.
• 🚀 Batch operations: easily create or drop all entities in a single command or lifecycle event.
• 🧪 Testability: definitions are just code so they’re easy to test, validate, and keep consistent.

Whether you're managing reporting views, business logic functions, or automation triggers, this package helps you treat SQL entities like real, versioned parts of your codebase---no more scattered SQL in migrations!

[!NOTE] Migration rollbacks are not supported since the definitions always reflect the latest state.

"We're never going backwards. You only go forward." -Taylor Otwell

📦 Installation

First pull in the package using Composer:

Optionally, publish the configuration file:

The package looks for SQL entities under database/entities/ so you might need to add a namespace to your composer.json file, for example:

[!TIP] This package looks for any files matching database/entities in the application's base path. This means it should automatically work for a modular setup where the entities might be spread across multiple directories.

Configuration

The package ships with a configuration file that controls automatic syncing behavior:

Syncing on Migration

When sync is enabled (the default), SQL entities are automatically kept in sync whenever migrations run. This means you can simply create or update your entity classes and they'll be refreshed the next time you run php artisan migrate, no need to manually run sql-entities:create or sql-entities:refresh.

Entities are also refreshed when there are no pending migrations, ensuring any newly added or updated entity definitions are always applied.

drop_on_migrate Behavior

The drop_on_migrate option controls how entities are synced during migrations:

When disabled (the default): Entities are refreshed after migrations finish using CREATE OR REPLACE where possible. If a refresh fails due to a schema change (e.g., a column was removed that a view references), the entity is automatically dropped and recreated. For migrations that require specific entities to be absent, you can use the withoutEntities() method for more granular control.

When enabled: All entities are dropped before migrations begin and recreated after they finish. This prevents migration failures caused by dependent schema changes, but means entities will be unavailable while migrations are running.

[!WARNING] If you run migrations while the application is still serving traffic (e.g., zero-downtime or rolling deployments), enabling drop_on_migrate will cause SQL errors for any requests that depend on those entities until migrations complete and the entities are recreated.

🛠️ Usage

🧱 SQL Entities

To get started, create a new class in a database/entities/ directory (structure is up to you) and extend the appropriate entity class (e.g. View, etc.).

For example, to create a view for recent orders, you might create the following class:

You can also override the name and connection with a property:

Or with an attribute. An attribute is used while the property is at its default; assigning a different value at runtime takes precedence. #[Connection] accepts a string or a UnitEnum.

🏷️ Attributes

Every configuration property has an attribute equivalent. Use one or the other. An attribute applies while the matching property is still at its default.

List attributes accept one value or an array. Flag attributes default to true; pass false to turn an inherited flag off.

Functions must define a return type, and triggers must define a table, timing, and events, either as a property or an attribute. PHPStan reports a missing definition. Include vendor/calebdw/laravel-sql-entities/extension.neon, or install phpstan/extension-installer to include it automatically.

🔁 Lifecycle Hooks

You can also use the provided lifecycle hooks to run logic before or after an entity is created or dropped. Returning false from the creating or dropping methods will prevent the entity from being created or dropped, respectively.

⚙️ Handling Dependencies

Entities may depend on one another (e.g., a view that selects from another view). To support this, each entity can declare its dependencies using the $dependencies property, the #[DependsOn] attribute, or the dependencies() method:

The manager will ensure that dependencies are created in the correct order, using a topological sort behind the scenes. In the example above, OrdersView will be created before RecentOrdersView automatically.

📑 View

The View class is used to create views in the database. In addition to the options above, you can use the following options to further customize the view:

Additionally, you can start a query against the view using the query() method:

Indexed Views (SQL Server)

SQL Server supports indexed views, which store query results on disk and are automatically maintained by the engine (no manual refresh needed). You can create these using the existing View class with characteristics and a created() lifecycle hook:

💿 Materialized View

The MaterializedView class is used to create materialized views in the database.

[!NOTE] Materialized views are currently only supported on PostgreSQL. Other drivers will skip materialized view entities automatically.

In addition to the options above, you can use the following options to further customize the materialized view:

Just like regular views, you can query a materialized view directly:

Refreshing data: Materialized views store their data on disk. To refresh the data (re-run the underlying query), use the refreshMaterializedData() method or the sql-entities:refresh-materialized-data command.

Self-scheduling: Materialized views can define their own refresh schedule using the schedule() method. Views with a schedule are automatically registered with Laravel's scheduler (with withoutOverlapping() enabled by default):

Return null from schedule() (the default) to disable automatic scheduling.

[!IMPORTANT] CREATE MATERIALIZED VIEW IF NOT EXISTS is used for creation, which means definition changes are not automatically applied. To update a materialized view's definition, use withoutEntities() in a migration to drop and recreate it.

Drop protection: Materialized views implement the RequiresExplicitDrop interface, which prevents them from being accidentally dropped during blanket operations like dropAll(). See the RequiresExplicitDrop section for details.

📐 Function

The Function_ class is used to create functions in the database.

[!TIP] The class is named Function_ as function is a reserved keyword in PHP.

In addition to the options above, you can use the following options to further customize the function:

Loadable functions are also supported:

📤 Procedure

The Procedure class is used to create stored procedures in the database. In addition to the options above, you can use the following options to further customize the procedure:

[!NOTE] SQLite does not support stored procedures. The grammar will skip procedure entities on SQLite connections.

⚡ Trigger

The Trigger class is used to create triggers in the database. In addition to the options above, you can use the following options to further customize the trigger:

🧠 Manager

The SqlEntityManager singleton is responsible for creating and dropping SQL entities at runtime. You can interact with it directly, or use the SqlEntity facade for convenience.

♻️ withoutEntities()

Sometimes you need to run a block of logic (like renaming a table column) without certain SQL entities present. The withoutEntities() method temporarily drops the selected entities, executes your callback, and then recreates them afterward.

[!TIP] If the database connection supports schema transactions, the entire operation is wrapped in one.

You can also restrict the scope to certain entity types or connections:

After the callback, all affected entities are automatically recreated in dependency order.

🛡 RequiresExplicitDrop

Most entities (views, functions, procedures, triggers) are cheap to drop and recreate: the operation is near-instant and the definitions live in your code. However, some entities are expensive to recreate. Materialized views, for example, store query results on disk; dropping one means the data is lost and must be recomputed on creation, which can take significant time for large datasets.

The RequiresExplicitDrop interface marks these expensive entities so they aren't accidentally dropped during blanket operations. MaterializedView implements this by default. Protected entities are only dropped when explicitly targeted or forced:

You generally don't need to apply this interface to regular views, functions, procedures, or triggers. It's intended for entities where the cost of recreating is non-trivial.

💻 Console Commands

The package provides console commands to manage your SQL entities.

🤝 Contributing

Thank you for considering contributing! You can read the contribution guide here.

⚖️ License

This is open-sourced software licensed under the MIT license.

🔀 Alternatives

• laravel-sql-views
• laravel-migration-views