Eloquent Ci Relations Laravel Package

Getting Started

This release is a compatibility bump: the package now accepts illuminate/database v13 (the Laravel 13 database layer) alongside its existing supported versions. For day-to-day use that means one thing — you can now install it in an app on the Laravel 13 line without composer fighting you, and everything you already do with the package keeps working on the new framework major.

Minimal steps to get productive:

1. Confirm what you're actually on.

   composer show --direct | grep -i laravel
   composer show <vendor>/<package>
   

   Compare the package's require block against your illuminate/database, laravel/framework, and PHP versions. Laravel 13 majors typically raise the PHP floor, so a stale CI image is the most common first failure.
2. Install and let discovery do its job. composer require <vendor>/<package>. The service provider should be auto-discovered; check php artisan about or php artisan package:discover output to confirm it registered rather than assuming.
3. Publish anything publishable, then read the config file before changing it. php artisan vendor:publish --provider="<Vendor>\<Package>\...ServiceProvider". The default config is usually the correct starting point; most "the package is broken" reports are a half-edited config that got cached.
4. Run the package's own migrations/seeders if it ships any, then php artisan migrate:status to confirm they landed on the connection you expected.
5. Smoke-test against a real query, not an empty table. Point the package at one existing model/table in a dev database and exercise a single read and a single write.

Where to look first when you're new to it: the package's README upgrade section (this release adds a new row to the support matrix — read the table, not just the headline), the config file it publishes, and its service provider. The provider tells you in thirty seconds whether the package decorates the connection resolver, registers a query macro, or ships its own grammar — that single fact determines how the rest of your integration will behave.

First use case: take an existing, boring query you already have in a repository or controller and route it through the package. You want to see the package's behaviour on your real schema and your real connection setup before you build anything on top of it. If it's a macro or builder-extension style package, do this on the query builder first (DB::table(...)), then on Eloquent — the two code paths are not always identical.

Implementation Patterns

Pin the major, float the minor. In composer.json, constrain to what you've verified: "<vendor>/<package>": "^1.6". Letting Composer resolve v13 support is fine on a branch, but a composer update on main shouldn't be able to move your database layer three majors without a diff.

Isolate the package behind your own boundary. Whatever the package does — custom casts, builder macros, connection decorators — call it from a small number of places (repositories, query scopes, dedicated action classes) rather than scattering it through controllers. This is what makes future major bumps cheap: when v2 or Laravel 14 arrives, you have one file to audit, not forty.

Prefer Eloquent scopes over ad-hoc builder chaining for anything reused. Packages that extend illuminate/database frequently do so at both levels, and the two surfaces drift. A local scope or a small query object becomes the single place where the package's API is exercised, which keeps the blast radius of an upgrade contained.

Test against the real connection, not a fake. Use RefreshDatabase plus SQLite in-memory for the fast suite, but keep one CI job on MySQL/Postgres — grammar-sensitive packages behave differently across drivers, and in-memory SQLite is a poor proxy for JSON, window functions, RETURNING, and identifier quoting.

Keep it out of the hot path in queue workers and Octane. If the package holds per-request state or mutates shared builder state, resolve it per-job rather than storing it on a singleton. Inject it, don't grab it from a container inside a loop.

Wire the compatibility check into CI, not into someone's memory. Add composer why-not <vendor>/<package> 13.x or a plain composer update --dry-run job against the newest supported framework line. That turns "does this package hold us back?" from a release-week archaeology project into a green or red build.

Gotchas and Tips

laravel/framework replaces illuminate/database. This is the single most common source of confusing conflict output. If a constraint mentions illuminate/database ^12.0 and you're on laravel/framework ^13.0, Composer will refuse even though the versions "look" fine. Use composer why-not illuminate/database 13.* and read the full tree before editing anything.

Newly added v13 support is not the same as v13 being the default. On a fresh Laravel 13 app you may need composer require <vendor>/<package>:^1.6 --with-all-dependencies so the transitive constraints get re-resolved. If Laravel 13 is still pre-release at the time you're reading this, expect to need minimum-stability/prefer-stable adjustments on a throwaway branch — not on main.

Don't infer "supports Laravel 13" as "drops Laravel 11/12." A support-matrix release is additive. Read the package's require block to see whether older majors were actually removed; if they were, that's a breaking change hiding in a minor version number, and your upgrade is no longer a patch.

Cached config will lie to you. php artisan config:cache bakes in the package's config at deploy time. Any change to connection names, table prefixes, or feature flags needs a re-cache. config:clear is the first command to run when behaviour differs between php artisan tinker and the running app.

Debugging: get the SQL before you blame the package. ->toSql() and ->getBindings() on the builder, or a temporary DB::listen(fn ($q) => logger($q->sql, $q->bindings)), will tell you within a minute whether the package generated bad SQL or whether the query was wrong to begin with. Enable DB::enableQueryLog() in a test when you need the full sequence.

Watch your table prefix and connection name. Anything that reaches into the schema or resolves connections internally can miss a non-default connection or a global prefix. If a feature silently returns nothing, test it with an explicit ->on('secondary') and a prefixed connection before filing a bug.

Extension points to know before you fork anything: the connection resolver (DB::resolverFor), custom grammars ($connection->withTablePrefix() / grammar substitution), and Builder::macro / Model::macro registration. Most behaviour you'd want to change is reachable through one of these from your own service provider — which is far more upgrade-safe than patching vendor code or pinning to a fork.

Upgrade recipe for this release: branch → bump the constraint to ^1.6 → composer update <vendor>/<package> --with-all-dependencies → run the full suite, including the MySQL/Postgres job → exercise one write path and one transaction/rollback path in staging → merge. The risk here is low and concentrated in dependency resolution, not in the package's runtime behaviour.