Core Laravel Package

Getting Started

• Confirm you can take it. v4.1.0 pins laravel/framework ^12.0 and therefore PHP 8.2+. If any app is still on Laravel 10/11, it must stay on the 4.0.x line — check composer.json for illuminate/* constraints before bumping.
• Upgrade path: composer require <vendor>/<package>:^4.1 in a branch, then run composer why-not <vendor>/<package> 4.1.0 if the resolver refuses. Most failures at this step are transitive packages pinning illuminate/support ^10|^11.
• Look here first: CHANGELOG.md/UPGRADE.md (the release note here is a one-liner, so the changelog is the real source of truth), then src/*ServiceProvider.php for bindings, config keys, and publishable assets.
• First use case: resolve the package out of the container rather than instantiating it, e.g. app(YourPackage::class) or its facade, and exercise one end-to-end happy path in php artisan tinker before wiring it into a controller. That confirms the service provider registers cleanly under Laravel 12's bootstrap/app.php style (withProviders / package auto-discovery) before you debug anything else.

Implementation Patterns

• Constructor injection over facades for anything you unit test; facades are fine in controllers and Blade. Resolve through the container so test-time swaps ($this->app->instance(...), $this->mock(...)) work.
• Config over code. Publish the config file once (php artisan vendor:publish --tag=<package>-config), commit it, and drive behaviour from config/<package>.php. Keep environment-specific values in .env and reference them from the config file only — never call env() from application code once config:cache is in play.
• Deploy sequence: composer install --no-dev → config:cache → route:cache → view:cache, with vendor:publish --force for public assets in the release step, not at runtime.
• Testing: use the package's fakes/assertion helpers where provided; otherwise bind a mock in setUp(). Target PHPUnit 11 (the Laravel 12 default) — data providers must now be static, and @dataProvider annotations are on the way out in favour of attributes.
• Queue/event integration: if the package dispatches events or jobs, wrap calls in Bus::fake() / Event::fake() in tests and confirm serialization works — a model or closure captured in a queued payload will fail on the worker even when the request path passes.
• Multi-app consistency: pin ^4.1 explicitly and keep a shared composer.lock policy across apps so you don't drift between 4.0 and 4.1 behaviour in staging vs production.

Gotchas and Tips

• Carbon 3 is the big one. Laravel 12 runs Carbon 3, where diffIn*() methods return floats and default to absolute values with inverted sign semantics. Any assertion like assertSame(1, $a->diffInDays($b)) or date arithmetic in your code around this package will silently break. Use diffInDays(..., absolute: false) and assertEqualsWithDelta where relevant.
• PHPUnit 11: static data providers, expectExceptionMessage matching changes, and --parallel behaving differently. If the package ships test helpers, re-read their signatures rather than assuming.
• Stale caches masquerade as bugs. After upgrading, run php artisan optimize:clear. A cached config from 4.0 with keys added or renamed in 4.1 will produce "missing argument" style errors that look like package faults.
• env() returns null once config is cached — if a new 4.1 config key reads env() at runtime in the package, set it in your published config file instead.
• Debugging registration issues: php artisan about shows discovered packages; composer dump-autoload fixes the classic "class not found after upgrade" when the package added files but your autoloader is stale.
• Extension points: prefer the documented binding overrides ($this->app->bind(Contract::class, Custom::class) in a service provider) and the published config over editing vendor files. If you must subclass an internal class, note it — that's the first thing to re-check on the next minor release.
• Thin release notes are a flag, not a blocker. "Upgrade to laravel 12" tells you about the framework floor and nothing about internal behaviour changes. Run the package's own test suite against your app (vendor/bin/phpunit --testsuite=feature) and diff the source between 4.0 and 4.1 tags before trusting a green composer update.