Laravel Sql Entities Laravel Package

Getting Started

• Install with composer require calebdw/laravel-sql-entities, then publish the config: php artisan vendor:publish --tag=sql-entities-config (check vendor/calebdw/laravel-sql-entities/README.md for the exact tag and provider registration).
• Look first at config/sql-entities.php (entity namespaces/paths, connection, driver gating) and at the package's src/Attributes directory — attributes are the primary configuration surface, so those classes are your API reference.
• Discover the available commands with php artisan list | grep -i sql before writing anything; the sync/discovery commands are what you'll actually run day-to-day.
• First use case: create a single database view as a PHP class under app/Sql/Entities (one class per entity, SQL body in a constant or heredoc), annotate it with the package's entity attribute, and run the sync command against your local DB. Once that round-trips, expand to functions/procedures/triggers only if your driver supports them.

Implementation Patterns

• One class per entity, attributes for metadata. Keep entity name, connection, and driver/version constraints in attributes on the class rather than in the config array. That keeps the SQL and its metadata co-located and diffable in review.
• Directory layout by kind. app/Sql/Entities/Views, /Functions, /Procedures, /Triggers, with the namespace registered in config. Discovery is class-scanning based, so a stable layout avoids surprises when the registry resolves entities.
• Deploy pipeline placement. Run the entity sync after php artisan migrate --force, as its own deploy step — not inside a migration. Views frequently depend on columns added by migrations, and burying view sync in a migration makes rollbacks and re-runs painful.
• Local vs. production modes. Use the destructive/refresh path locally (drop-and-recreate is fine, it's your dev DB) and the idempotent create-or-replace path in CI/production. Wire this to an env flag rather than remembering to pass a flag by hand.
• Testing. In TestCase::setUp() after RefreshDatabase, run the entity sync programmatically so your test DB has the views/functions under test. This catches ordering problems between entities early.
• Dependency ordering. If view B selects from view A, define both as classes and let the package's ordering handle it; where it doesn't, encode the dependency explicitly rather than relying on filesystem order.
• Extending attribute reads. If you need custom attribute-driven behavior on your own entity base class, extend the package's shipped ReadsClassAttributes trait — not the framework one. See gotchas.

Gotchas and Tips

• ReadsClassAttributes is now shipped by the package (v1.1.1). Laravel's framework version of this trait is Laravel 13-only, so use Illuminate\...\ReadsClassAttributes; will fatal on Laravel 12. If you had a local copy or polyfill to work around the v1.1.0 breakage, delete it now — two definitions of the same trait name in your autoload path is a confusing way to spend an afternoon.
• Upgrade path v1.1.0 → v1.1.1 is safe but verify on 12. The release is explicitly a Laravel 12 compatibility fix. If you're on Laravel 12 and pinned v1.1.0, attributes were likely broken or CI-failing; bump and re-run your entity sync to confirm configuration is actually being read.
• Static analysis on entity lookup. v1.1.1 removed a non-literal class-string being passed to Collection::get(). If you extend or wrap the entity collection/registry, pass a concrete Foo::class rather than a variable holding a class name, or PHPStan (at the levels this package now targets) will flag it. Same discipline applies to your own subclass code.
• Discovery is autoload-dependent. New entity classes are found by class scanning — run composer dump-autoload (and clear config/route caches) after adding one, or the sync will silently do nothing for the file you just wrote.
• Octane / long-running workers. Attribute metadata and the entity registry get cached in process memory. After changing an entity class, php artisan octane:reload — otherwise you'll debug "why is my SQL unchanged" for twenty minutes.
• Driver divergence is the real pitfall. Materialized views (Postgres), CREATE OR REPLACE VIEW semantics (MySQL/MariaDB), and stored procedures (unsupported on SQLite) behave differently. Gate entities per driver in attributes/config, and keep a SQLite-compatible subset for tests or your test suite won't boot.
• Privileges. Production DB users often lack CREATE VIEW/CREATE TRIGGER. Confirm grants before the first prod deploy rather than during it.
• Debug the generated SQL. Before trusting a sync, log or dump the statement the package builds for one entity — quoting, schema prefixing, and DEFINER clauses on procedures are common sources of "works locally, fails in prod."
• Data loss on refresh. A destructive sync against a materialized view or a table-backed entity drops data. Treat the refresh command as local-only and never leave it on a schedule.