Eloquent Utils Laravel Package

Getting Started

The 0.4.0 release hard-pins the package to a modern runtime: PHP 8.4+ and Laravel 12+. Before you do anything else, confirm your application can satisfy that floor — composer require will fail fast on 8.3/11.x, so validate the host app first rather than debugging a confusing solver error later.

Minimal adoption path:

1. Verify the platform. Check php -v on every environment (local, CI, staging, prod) and your composer.json require block. If you use config.platform.php in composer.json to emulate the deploy target, that value must be bumped to 8.4.0 or the install will resolve against the wrong runtime.
2. Upgrade the host app to Laravel 12 first. Do not attempt to move the package and the framework in the same commit. Get the app onto Laravel 12 and PHP 8.4 with a green test suite, then add the package. This keeps the failure surface to one variable.
3. Install and inspect. Run composer require <vendor>/<package>:^0.4, then immediately look for a service provider and any publishable assets: php artisan vendor:publish --provider="...ServiceProvider" (or --tag=<package>-config). Read the config file top-to-bottom before touching it — it's the contract for everything downstream.
4. Look first at: the package's README install section, the published config file, and the service provider's register()/boot() methods. Those three tell you what's auto-wired, what's overridable, and what the intended entry point is. If the package ships a facade, its docblock @method annotations are usually the fastest API reference.
5. First use case: pick the package's single simplest happy path — resolve the service from the container (app(SomeService::class)) and call one method in a Tinker session (php artisan tinker). Confirm the container binding and config are live before writing application code. Then wrap that call in a feature test.

Because 0.4.0 is a major-adjacent jump that removes 8.3 and 11.x rather than deprecating them, treat this install as a new integration, not a patch. There is no transition period to lean on.

Implementation Patterns

Container-first integration. Resolve the package's services from the container rather than instantiating them directly. This is what makes the config file, driver swaps, and test doubles actually work. Constructor-inject into your own services and controllers; never new a package class that has a config dependency, or you'll silently bypass the config.

Config as the primary lever. Publish the config and keep your edits minimal and commented. Prefer environment variables for anything that differs per environment, and commit the config file so drift is reviewable. In tests, use config()->set(...) in setUp() rather than editing the file — and remember to restore it, since config mutations leak across tests in the same process.

Wrap it behind your own boundary. For anything non-trivial, put a thin adapter or interface in front of the package. This is especially important here: 0.4.0's removal of Laravel 11 support shows this package tracks framework versions aggressively, so you should expect the next release to make a similar jump. A single adapter class means the next upgrade touches one file instead of fifty call sites. Bind your interface to the package implementation in a service provider.

Queue and job integration. If the package does remote or heavy work, drive it from a job rather than a request. Keep the job small: resolve the service, call it, handle the result. This also isolates failures from the HTTP path and makes retries possible. Set explicit $tries and $timeout — package defaults for these are rarely tuned to your workload.

Testing patterns. Use RefreshDatabase or an equivalent state reset, and fake any outbound HTTP the package performs so your suite doesn't depend on a third party. For integration confidence, write one contract test per package capability that exercises the real config path, and keep everything else fast and faked. Pin the package to a minor range (^0.4) in composer.json and commit composer.lock — during a 0.x lifetime, surprise breaks are the default assumption.

CI matrix. Update the pipeline in the same PR as the upgrade: php-version: 8.4 on every job, plus the shivammathur/setup-php matrix entry. If you run a multi-version matrix to stay compatible with older apps, drop 8.3 from it — it cannot install this package. Also bump your Docker base images (php:8.4-cli, php:8.4-fpm) and any Heroku/Forge/Laravel Cloud build image.

Static analysis and tooling. PHPStan/Larastan, Pint, and Rector all need to understand 8.4 syntax. Bump them together; an older PHPStan running against 8.4 code will produce parse errors that look like package bugs but aren't.

Gotchas and Tips

The 0.4.0 upgrade is a hard cut, not a deprecation. PHP 8.3 and Laravel 11 were removed, not deprecated. There is no shim, no compatibility layer, and no warning period. If you are on Laravel 11 today, you cannot receive 0.4.0 fixes and features without upgrading the framework. Plan this as a coordinated upgrade with a rollback point (branch + tagged release), not a composer update. Check whether you're currently on ^0.3 and whether that line is still receiving security patches — the release notes are silent on it, which is itself worth asking the maintainer about.

Watch for transitive conflicts. The package now requires Laravel 12, which pulls a newer illuminate/* set than an 11.x app has. Even if you only use the package in one module, the framework constraint applies globally. Run composer why-not laravel/framework 12.0 if resolution stalls — it will name the offending dependency faster than reading the solver output.

PHP 8.4 itself has deprecations that will surface on upgrade. Most notably implicitly nullable parameters (function foo(string $x = null) → must become ?string $x). Your own code will emit these even if the package is clean. Run the test suite with error_reporting(E_ALL) and fail on deprecations, or they'll accumulate silently and break on 9.0.

Config cache is the classic silent failure. After any config or .env change, run php artisan config:cache (or config:clear in local dev). A stale cached config makes package behaviour look nondeterministic and wastes hours. If you deploy with config:cache, remember env() calls outside config files return null at runtime — this bites packages that read env lazily.

Publish tags differ per version. If you previously published the config under 0.3, 0.4.0 may have added or renamed keys. Diff the vendor config file against your published copy after upgrading and reconcile manually — do not blindly re-publish, or you'll lose customisations.

Use the exception handler and logs first when debugging. Most integration failures present as a container resolution error (binding missing) or a config validation exception (a required key absent). Log the resolved config in a failing test temporarily — a surprising number of issues are just a null where a credential should be.

Extension points to prefer. Override via container bindings, published config, and driver implementations rather than subclassing internals. If the package exposes events, listen to them instead of monkey-patching. Avoid touching vendor/ — with a version this young and this willing to break compatibility, forks and patches become maintenance debt very fast. If you genuinely need a behaviour change, open an issue; a 0.x package maintainer is usually receptive, and an upstream fix survives the next version bump.

Pin and stage. Stay on ^0.4 with a committed lockfile. Treat every minor release of a 0.x package as potentially breaking and read the notes before running composer update in CI — 0.4.0 is a clear demonstration of why.