Laravel Sortable Laravel Package

Getting Started

• Confirm your app meets the new floor before anything else: Laravel 10+ (Laravel 13 supported) and PHP 8.2+. Laravel 9 and PHP 8.0/8.1 are no longer supported in 3.0.0 — check composer.json (laravel/framework, php) and your CI matrix first.
• Install with composer require <vendor>/<package>:^3.0, then run php artisan vendor:publish --tag=<package>-config if the package ships config. Read the published config file top-to-bottom — it is the fastest map of what the package actually does.
• Look first at: the package's README "Upgrade" section, config/<package>.php, and any service provider bindings. Those three tell you the extension points before you write a line of code.
• First use case: wire the package into a single, low-risk flow (one controller or one artisan command) and verify with php artisan tinker before touching migrations or queues.
• If upgrading from 2.x, run composer why-not <vendor>/<package> 3.0.0 to see exactly which of your other dependencies are blocking the bump — that is usually the real work, not the package itself.

Implementation Patterns

• Resolve from the container, don't new it. Bind the package's client/manager in a thin repository or action class and inject it. This keeps the package out of your domain code and makes it swappable in tests.
• Config over hardcoding. Put credentials and endpoints in config/<package>.php, values in .env. Cache with php artisan config:cache in deploy and confirm nothing reads env() at runtime outside config files.
• Fake it in tests. Most Laravel packages expose a ::fake() or a contract you can bind. Prefer that over hitting the network in feature tests; assert on the recorded calls rather than return values where possible.
• Queue the slow paths. Anything the package does over HTTP belongs in a job with $tries, $backoff, and failed() handling. Wrap calls in retry([...], $sleep, fn () => ...) at the boundary.
• Log context, not noise. Add a middleware or job middleware that pushes a correlation ID into the package's log context so failures are traceable across retries.
• Adapter seam for multi-version support. If you maintain several apps on different Laravel majors, isolate the package behind one interface per app rather than branching on app()->version() in business logic.
• Validate at the edge. Package exceptions should be caught in a dedicated Handler mapping or a renderable exception so users get a 4xx/5xx instead of a stack trace.

Gotchas and Tips

• The 3.0.0 bump is a hard floor, not a soft one. Laravel 9 and PHP 8.0/8.1 are gone. Anything still on those — an old CI job, a stale Docker base image, a platform.php override in composer.json — will fail to resolve. Check composer.json config.platform explicitly; it silently pins the version Composer negotiates against.
• Laravel 13 support means skeleton drift. New majors change default config stubs, service provider registration, and sometimes the Handler. Re-publish config after upgrading and diff it against your published copy — don't blindly overwrite, but don't skip the diff either.
• Transitive constraints bite before the package does. Run composer update <vendor>/<package> --with-dependencies -W and inspect the dry run. If a third-party package lags on Laravel 13, you are blocked, and downgrading the package is usually cheaper than a fork.
• Deprecations are silent at runtime. Bump APP_DEBUG in staging and scan storage/logs after a test run; PHP 8.2+ dynamic-property and null-coalescing deprecations surface there long before they become errors in 4.0.
• Config cache hides stale files. After any package upgrade, php artisan config:clear && php artisan cache:clear before debugging "it works locally but not in staging."
• Extension points to know: the service provider's bindings/singletons array, Macroable traits on the client, and any Factory/Builder the package returns. Macros are the least invasive way to add behaviour without forking.
• Pin the major. Use "^3.0" in composer.json and commit composer.lock. Given 3.0.0 drops two Laravel majors and two PHP minors, treat minor releases as reviewable changes and read the changelog before composer update.
• Watch for a 3.1/4.0 roadmap. A release that removes PHP 8.0-8.1 support is usually the first step in a tightening cycle; assume the next major requires PHP 8.3+ and plan CI accordingly.