Laravel Eloquent Cache Laravel Package

Getting Started

This release is a compatibility bump — v0.9.2 adds Laravel 12 support to the existing feature set. Nothing in the API surface changed, so the onboarding path is unchanged from previous 0.9.x releases.

1. Confirm your constraints. Check composer.json in your project for laravel/framework and php versions. v0.9.2 is the first release that will resolve against Laravel 12 — on Laravel 12 you must be on this version (or later), so run composer require <vendor>/<package>:^0.9.2 rather than a loose constraint.
2. Publish config and migrations first.

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   php artisan migrate
   

   Read the published config/<package>.php before migrating — defaults are sane but almost always need at least the model/table overrides changed.
3. Where to look first. The service provider is the map of the package: it registers bindings, config merges, and publishes. From there, follow the facade or the main manager class named after the package — that's where the public API lives.
4. First use case. Wire up the smallest end-to-end flow: one model through the package's primary entry point (a trait, a cast, or a manager method), assert the result in a feature test, then expand. Doing this in a test rather than tinker gives you a regression net for the Laravel 12 upgrade.

If you're upgrading a Laravel 11 app, the package is the easy part — do the framework upgrade first, get the app green, then bump the package.

Implementation Patterns

Dependency injection over facades. Resolve the package's manager/contract from the container in constructors and jobs. Facades are fine in controllers and Blade, but injectable contracts make tests trivially swappable and keep you honest about what the package actually exposes.

Compose through traits where offered. Most packages in this class ship a trait for your Eloquent models (e.g. HasPackageFeature). Prefer the trait to hand-rolled model methods: it's the surface the package's own internals detect, and it survives minor-version upgrades.

Wrap it behind your own service. Introduce a thin application-level service (App\Services\...) that calls the package. When a package is at 0.9.x, its public API is pre-1.0 and can shift. One wrapper class means a future rename is a single-file change, not a grep across fifty call sites.

Jobs and queues. Anything that touches the package on a queue worker needs the same config resolved — verify it works under php artisan queue:work --once in a test, not just in a request. Config caching (php artisan config:cache) is the classic way package config silently disappears in production.

Testing integration.

• Use the package's shipped test helpers/fakes if it provides them; otherwise bind a mock of the contract in your test case's setUp.
• Use RefreshDatabase plus the published migrations so your tests exercise the real schema rather than a hand-rolled fixture.
• For Laravel 12 specifically, add one smoke test that boots the application and resolves the package's main binding — that catches provider registration regressions cheaply.

Multi-tenant / multi-connection apps. If you override the connection or table per tenant, set it through the package's config or manager method rather than mutating global config at runtime — the latter leaks across queued jobs.

Gotchas and Tips

0.x versioning is the headline risk. Pre-1.0 packages make no semver guarantees on the public API. Pin to ^0.9 (not *), commit composer.lock, and read the changelog before every minor bump. Treat v1.0 as the point where you can relax.

Laravel 12 upgrade ordering. On a mixed-version team, the package won't install until the framework is bumped, and other packages likely have the same constraint. Use composer why-not <vendor>/<package> 0.9.2 to see exactly what's blocking resolution instead of guessing from a wall of solver output. Clear the solver cache with composer clear-cache if constraints look stale.

Config caching bites. Always test with php artisan config:cache enabled at least once before deploying. Packages that read config inside a closure or during a service provider's register() can behave differently once cached.

Publishing overwrites. vendor:publish with --force will clobber your customized config. Prefer --tag scoping and diff before forcing; keep environment-specific values in .env and reference them from config rather than editing published files.

Migration collisions. If you already have tables the package expects, publish migrations and edit them (or use --pretend to inspect first) rather than letting the package's migrations run blind. Duplicate index/column errors on deploy are the usual symptom.

Debugging. The package's exceptions are often wrapped — catch the package exception, log $e->getPrevious() for the real cause. Enable query logging (DB::listen) when results look wrong; most "package bug" reports turn out to be an unexpected connection or a scope leaking from a global scope on your model.

Extension points to prefer. Contracts bound in the container, published config, and events. Avoid subclassing internal classes or reaching into protected properties — that's the code most likely to break in the next 0.x bump and again at 1.0.

When in doubt, test the upgrade in isolation. A branch with only the framework bump plus this package's bump, running your existing suite, tells you in minutes whether v0.9.2 is clean for you — far faster than debugging it through a full feature release.