Getting Started

Confirm compatibility before touching code: v1.3.0 targets PHP 8.4 and Laravel 13. If you're on Laravel 11/12 or PHP 8.3, stay on the 1.2.x line; don't force the upgrade just to get a patch release.
Verify the published constraints: composer show <vendor>/<package> --all should show php: ^8.4 and laravel/framework: ^13.0 (or equivalent). If Composer can't resolve those, stop — the tag is not installable.
Install and publish: composer require <vendor>/<package>:^1.3, then php artisan vendor:publish --tag=<package>-config (or --provider=...). Run php artisan package:discover if auto-discovery is disabled.
First use case: resolve the package's main entry point from the container in php artisan tinker and call one read-only method. Then write a small feature test that asserts the config merge and one happy-path call — that's your upgrade smoke test.

Implementation Patterns

Prefer constructor injection over facades in application code; facades are fine in controllers and Artisan commands but make tests more implicit. Bind the package's interface to your own adapter if you need to swap implementations later.
Treat published config as the contract: set environment-specific values in .env, reference them in config/<package>.php, and run php artisan config:cache during deploy to catch serialization problems early.
If the package wraps an HTTP API, isolate it behind one adapter class and use Http::fake() in tests. This keeps the Laravel 13 upgrade from leaking into your domain code.
Upgrade workflow: branch → bump the constraint → composer update <vendor>/<package> -W → run the full suite with E_ALL → run php artisan about and smoke test queue/event paths → stage before production. A major-version compatibility bump deserves a staging pass even if the package diff is small.
In Laravel 11+ skeleton apps, provider registration lives in bootstrap/providers.php, not config/app.php. Register your own bindings in a provider that runs after the package's provider so overrides win.
Use the package's extension points (bindings, macros, events) rather than editing vendor files. Publish and edit config/migrations, and use Config::set() in tests instead of mutating config files.

Verify the Laravel 13 claim first. Laravel 13 is not a stable released major as of writing. If composer update can't resolve laravel/framework:^13.0, the tag is effectively unusable — check Packagist metadata and the package's CI matrix before planning an upgrade.
PHP 8.4 deprecations: implicit nullable parameters (function f(Type $x = null)) now emit deprecation notices. Run tests with error_reporting=E_ALL and convertDeprecationsToExceptions="true" in phpunit.xml so these fail loudly rather than silently accumulating.
config:cache masks runtime .env reads. If behavior differs between local and production, run php artisan config:clear and compare — this is the most common "works on my machine" cause with config-driven packages.
Auto-discovery can be disabled or stale. If the package "isn't there", check php artisan package:discover and inspect bootstrap/cache/packages.php.
Pin the minor if you need stability: "<vendor>/<package>": "1.3.*" rather than ^1.3. A ^ constraint on a fresh major-support release can pull future minors you haven't tested.
Debugging resolution conflicts: composer why-not <vendor>/<package> 1.3.0, php artisan about, and app()->bound(...) checks in tinker. These three cover most "package not loading" cases.
Don't edit vendor files. Publish config and migrations, override bindings in a later-registered provider, and keep the package's service provider untouched so future upgrades remain clean.