Magic Installer Laravel Package

Getting Started

v1.4.6 is a compatibility release: the only advertised change is Laravel 13 support. Treat it as a green light to run the package on a Laravel 13 app, not as a feature release — nothing in the public API is reported to have changed.

Minimal steps:

1. Verify the constraint before upgrading. Run composer why-not vendor/package 1.4.6 on your Laravel 13 app. If it reports a conflict, the blocker is almost always a transitive illuminate/* constraint or the PHP floor, not the package itself. Check the package's composer.json require block for illuminate/support, illuminate/contracts, and php.
2. Install or bump in a branch: composer require vendor/package:^1.4.6. If you're coming from a pre-1.4.6 pin, read the diff of composer.json and the service provider first — a "support" release is usually constraint-only, but confirm.
3. Look first at the service provider. Open src/*ServiceProvider.php and note three things: what it binds as singletons, what it merges from config (mergeConfigFrom), and what it registers conditionally (console vs. HTTP, runningInConsole()). That tells you the integration surface in under five minutes.
4. Publish, then diff. php artisan vendor:publish --provider="Vendor\Package\...ServiceProvider" (or --tag=config). If a config file already exists in config/, diff the published version against yours — new keys in a major-bump release are the most common silent breakage.
5. First use case: wire the package into one non-critical path behind a config flag, and cover it with a single feature test that boots the container. If that passes on Laravel 13, you have de-risked the upgrade; expand from there.

If the package ships artisan commands, php artisan list after install is the fastest way to see what it actually exposes. php artisan about confirms the framework version and discovered providers in one shot.

Implementation Patterns

Resolve from the container, never new. A package that supports multiple Laravel majors will change constructor signatures across versions. Type-hint the contract or the concrete class in your controller/job constructor and let the container build it. This is the single highest-leverage habit for surviving future upgrades.

Rebind rather than fork. If you need to swap the package's implementation (a custom HTTP client, a different storage driver), bind your class to the package's interface in your own AppServiceProvider::register() after the package provider runs. Package providers register before app providers, so your binding wins. This lets you take patch upgrades without patching vendor code.

Config-first customization. Anything the package exposes via config/package.php should be set through config() and env vars in .env, not edited in the published file. Publish once, commit the file with values reading from env(), and future releases that add keys will merge cleanly.

Test against the boundary. Use the package's fakes if it ships them (Package::fake()), otherwise write an integration test with RefreshDatabase that exercises one real call path. Fakes that don't exist get hand-rolled in tests/Support/ — don't mock the package's internals, mock the transport (HTTP client, queue, filesystem) with Http::fake(), Queue::fake(), Storage::fake().

CI matrix. If you support both Laravel 12 and 13, test both. The cleanest setup is a matrix on laravel/framework with composer update --prefer-lowest on one leg to catch constraint drift early. A package release that only advertises support is a good moment to confirm your matrix actually covers the new major.

**Queue and event side. ** Check whether the package dispatches jobs or events — grep -r "dispatch(" vendor/vendor/package/src. If it does, set the connection/queue explicitly in config rather than inheriting the default, so a deploy that changes QUEUE_CONNECTION doesn't silently reroute package work.

Gotchas and Tips

"Add Laravel 13 support" rarely means "tested against Laravel 13." The constraint bump is mechanical; the test run is not. Before trusting it, exercise your app's actual usage path on 13 — especially anything touching the container, Eloquent boot events, or config resolution, which are the areas Laravel majors usually move.

Composer will happily resolve to an older patch. If you've pinned "vendor/package": "^1.3" and 1.3.x is what satisfies your Laravel 12 constraint, you may not be on 1.4.6 at all. Run composer show vendor/package and read the actual installed version, not the constraint.

Stale caches masquerade as broken packages. After a bump: php artisan config:clear, php artisan package:discover, composer dump-autoload. Symptoms like "class not found" or "config key returns null" are almost always one of those three, not the release.

Publish tags are not stable across releases. --tag=config may not exist; --provider= always works. If a publish overwrites files unexpectedly, check vendor/vendor/package/src/*ServiceProvider.php for the publishes() array before running it in a dirty working tree.

Debug the registration, not the code. If the package appears inert, verify discovery: php artisan about lists discovered providers; a missing entry means extra.laravel.providers in the package's composer.json didn't match, or you're on a cached bootstrap/cache/packages.php. Delete that file and re-run.

Extension points, in order of preference: container binding override → manager extend() for driver-style packages → macros if the package exposes a macroable class → events. Forking is the last resort; if you must, use a Composer replace/VCS path repository so the divergence is visible in composer.json rather than hidden in vendor/.

Don't pin the exact patch. ^1.4.6 gets you future Laravel 13 fixes; 1.4.6 guarantees you'll be re-editing composer.json next month. Constrain the major, trust the semver, and lean on your CI matrix.