Laravel Segment Laravel Package

Getting Started

• Pin the constraint. v1.9.0 is the first release that declares Laravel 13 support, so require ^1.9 (not ^1.8) in composer.json; older tags will fail dependency resolution on a Laravel 13 app.
• Check platform requirements first. Laravel 13 raises the PHP floor, so confirm php in composer.json and your CI image match before chasing package-level errors — most "package won't install" reports after this release are actually PHP-version mismatches.
• Look at the service provider and config file first. The provider is the map of the package: what it binds, what it publishes, and whether it registers via package discovery. Publish the config (php artisan vendor:publish --provider="...") and read it top to bottom before writing any code.
• First use case. Install into a throwaway Laravel 13 skeleton, publish config, and drive the package's default behaviour against a small seeded dataset. This gives you a known-good baseline to diff against when you wire it into the real app.

Implementation Patterns

• Bind through the container, not the facade. Resolve the package's contract (or concrete class) via constructor injection in your own services/jobs so tests can swap it; keep facade calls at the edge (controllers, commands).
• Config as the integration seam. Anything environment-dependent (queues, drivers, API endpoints, table names) belongs in config/<package>.php and is read from env() only inside that file — this keeps config:cache working in production.
• Wrap it behind your own interface when the surface is wide. A thin adapter (App\Support\...) limits upgrade pain the next time a major Laravel release lands, since only the adapter needs touching.
• Test with the framework's own helpers. RefreshDatabase for anything persisted, Http::fake() / queue and event fakes for outbound behaviour, and a small integration test that asserts the provider actually registers on a bare app.
• CI matrix. Once a package claims Laravel 13 support, run laravel/framework: ^12.0|^13.0 across your supported PHP versions. Compatibility claims regress quietly; a matrix is the cheapest way to catch it.
• Upgrade workflow. Bump the constraint → composer update <vendor>/<package> -W → php artisan package:discover → clear cached config/routes → run the suite. Do it on a branch so the diff is reviewable.

Gotchas and Tips

• Silent resolution failures. If Composer refuses Laravel 13, run composer why-not laravel/framework 13.* — it's usually a transitive dependency with a stale constraint, not this package.
• Stale caches after composer update. config:cache and the discovery manifest both survive an upgrade and can mask new bindings. Clear config, cache, route, and view before concluding anything is broken; in production remember to re-run config:cache after deploy.
• Package discovery. If the provider is auto-discovered, do not also add it to providers in config/app.php — double registration produces confusing duplicate-listener behaviour.
• Config edits vanish. Changes made directly in config/<package>.php are safe, but files republished with --force will overwrite them; keep local overrides in a separate config key or an env-driven value.
• Deprecations are the real signal. A Laravel 13 support bump often means the package silenced deprecations rather than eliminated them. Run your suite with deprecation reporting enabled once, and note anything that will break in Laravel 14.
• Extension points to know. Published config, the container bindings in the provider, and any documented events/macros are the sanctioned customisation surface. Prefer those over subclassing internals, which are the most likely thing to change in the next minor.
• Pin in composer.lock, not just composer.json. For a compatibility-only release, commit the lockfile change so every environment runs the same tag.