https://github.com/calebdw/laravel-sql-entities
Manage SQL entities in Laravel with ease!
https://github.com/calebdw/laravel-sql-entities
Last synced: about 1 month ago
JSON representation
Manage SQL entities in Laravel with ease!
- Host: GitHub
- URL: https://github.com/calebdw/laravel-sql-entities
- Owner: calebdw
- License: mit
- Created: 2025-04-11T20:40:53.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2025-04-12T06:32:22.000Z (about 1 month ago)
- Last Synced: 2025-04-12T07:25:27.245Z (about 1 month ago)
- Language: PHP
- Size: 40 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
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](https://www.twitch.tv/theprimeagen/clip/DrabAltruisticEggnogVoHiYo-f6CVkrqraPsWrEht)
## 📦 Installation
First pull in the package using Composer:
```bash
composer require calebdw/laravel-sql-entities
```
The package looks for SQL entities under `database/entities/` so you might need to add
a namespace to your `composer.json` file, for example:
```diff
{
"autoload": {
"psr-4": {
"App\\": "app/",
+ "Database\\Entities\\": "database/entities/",
"Database\\Factories\\": "database/factories/",
"Database\\Seeders\\": "database/seeders/"
}
}
}
```
> [!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.
## 🛠️ 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:
```php
select(['id', 'customer_id', 'status', 'created_at'])
->where('created_at', '>=', now()->subDays(30))
->toBase();
// could also use raw SQL
return <<<'SQL'
SELECT id, customer_id, status, created_at
FROM orders
WHERE created_at >= NOW() - INTERVAL '30 days'
SQL;
}
}
```
You can also override the name and connection:
```php
connection->statement(<<name()} TO other_user;
SQL);
}
#[Override]
public function dropping(Connection $connection): bool
{
if (/** should not drop */) {
return false;
}
/** other logic */
return true;
}
#[Override]
public function dropped(Connection $connection): void
{
/** logic */
}
}
```
### 🧠 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.
```php
create(RecentOrdersView::class);
resolve('sql-entities')->create(new RecentOrdersView());
// Similarly, you can drop a single entity using the name, class, or instance
SqlEntity::drop(RecentOrdersView::class);
// Create or drop all entities
SqlEntity::createAll();
SqlEntity::dropAll();
// You can also filter by type or connection
SqlEntity::createAll(type: View::class, connection: 'reporting');
SqlEntity::dropAll(type: View::class, connection: 'reporting');
```
### 🚀 Automatic syncing when migrating (Optional)
You may want to automatically drop all SQL entities before migrating, and then
recreate them after the migrations are complete. This is helpful when the entities
depend on schema changes. To do this, register the built-in subscriber in a service provider:
```php
