Apposite Laravel Package

Getting Started

• Treat v5.0.0 as a compatibility/maintenance major first: the notes list no new runtime features, so the immediate work is aligning your app and CI with PHP 8.3 and Laravel 13.
• Before upgrading, confirm php -v is 8.3+ and laravel/framework resolves to ^13.0. Run composer why-not vendor/package 5.0 to see which constraint is blocking the upgrade.
• If you are on Laravel 12 or older, do not force v5. Pin the last tagged release that supports your Laravel version, for example "vendor/package": "4.*", and schedule the Laravel 13 migration separately.
• Look first at the package’s composer.json (php and illuminate/* constraints), its service provider registration, and any publishable config. Then diff the package’s public config and public classes between your pinned tag and v5 to catch API changes the release notes do not mention.
• First use case after upgrading: exercise the package’s main integration path in your app—a facade call, middleware, console command, model trait, or event listener—and run your existing feature tests. If you plan to contribute or debug the package itself, use ./dev; it runs the package in Podman without requiring host PHP or Composer.

Implementation Patterns

• Upgrade in a dedicated branch: bump to ^5.0, run composer update vendor/package --with-dependencies, then republish config only if the package documents changes. Diff published config instead of blindly overwriting with --force.
• Wrap package usage behind a small application adapter or service class where practical. Keeping package facades, DTOs, and exceptions out of domain code makes future major-version upgrades a one-file change.
• Rely on Laravel package discovery unless the package explicitly requires manual provider registration. For Laravel 13, verify the provider does not call APIs removed in the new major.
• Update your test suite to PHPUnit 12 conventions: attributes such as #[Test] and #[DataProvider] instead of annotations, and check for deprecations before assuming package test helpers are compatible.
• Add PHP 8.3 and Laravel 13 to your CI matrix. Use Laravel Pint as a formatting gate (vendor/bin/pint --test) scoped to your own code, not vendor/.
• Remove stale Scrutinizer status checks or badges if you copied them from the package. The package no longer uses Scrutinizer, and your branch protection should not depend on it.
• Standardize package contribution workflows on ./dev. It provides a reproducible Podman environment with no host PHP/Composer requirement, which is useful for bug reports and pull requests.
• Do not rely on Node tooling for package assets in v5. If the package previously shipped frontend assets built with Node, consume the published assets from the tagged release rather than rebuilding them, or stay on the last tag that included the Node build.

Gotchas and Tips

• The critical pitfall is that v5 is not a drop-in for PHP 8.2 or Laravel 12. Composer will block it, and forcing the constraint can produce runtime failures. Pin an older tagged release and document the reason in composer.json.
• “Only the latest major version is supported” means fixes for older lines stop. Treat this as a migration deadline, not a permanent fork. Track the package’s support policy and plan the Laravel 13 upgrade.
• The release notes emphasize tooling changes—Pint, PHPUnit 12, Podman, Scrutinizer removal—not feature changes. Do not assume zero API changes; run integration tests and diff public classes and config between tags.
• ./dev is for the package repository, not your application deployment. Use it to reproduce issues or contribute; if Podman is unavailable, use an equivalent PHP 8.3/Laravel 13 container.
• Pint can reformat generated stubs or published config if run over the wrong paths. Scope it to app/, config/, tests/, and your own package code; exclude vendor/ and generated files.
• PHPUnit 12 deprecates or removes several older behaviors. If package test utilities rely on annotations or legacy expectation APIs, expect warnings. Run vendor/bin/phpunit --display-deprecations and fix your own suite first so package warnings are distinguishable.
• Debugging upgrade failures: use composer show vendor/package to confirm the resolved version, composer why-not for the blocking constraint, and php artisan about for the Laravel version. After upgrading, run php artisan optimize:clear so cached package config and routes do not mask new defaults.
• Verify extension points after upgrading: published config keys, container bindings, events/listeners, and custom drivers or managers. These are the most likely places where behavior changes even when the release notes are tooling-only.