Laravel Tenantable Laravel Package

Getting Started

• Check the compatibility matrix before anything else. Version 2.7.0 is the first release with Laravel 13 support, so it is the minimum version to install on a Laravel 13 app. On Laravel 11/12 you can stay on 2.7.0 as well — the release is additive, with no removals or deprecations listed.
• Install and pin the constraint deliberately:

  composer require <vendor>/<package>:"^2.7"
  

  Use ^2.6 only if you are still on Laravel 12 and want to defer the upgrade; do not use * during the Laravel 13 transition.
• Read the package's README and UPGRADING/CHANGELOG first. For 2.7.0 the only change is framework support, so no migration steps are expected — but confirm there is no unpublished config or migration stub added since the version you last used.
• Verify what was auto-registered. Confirm the service provider is picked up by package discovery and, if the package ships them, publish only the assets you actually intend to own:

  php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider"
  

• First use case: install into a fresh Laravel 13 skeleton, publish config, run the package's example from the README or its test suite (vendor/bin/phpunit --testsuite=... inside the package, or a single smoke test in your app). This validates the new framework path end-to-end before you touch a real project.

Implementation Patterns

• Upgrade path for existing apps. Bump the package and the framework together in one branch, then run composer why-not <vendor>/<package> 2.7 to see exactly which locked dependency is blocking. Do the package bump before the framework bump where possible, so any failure is attributable.
• Dual-support window. If you maintain several apps on mixed Laravel versions, keep a CI matrix running the lowest and highest supported framework versions against the same package constraint. 2.7.0 being additive makes ^2.7 safe to use across Laravel 11–13 in most cases; the matrix is what proves it.
• Resolve from the container, not with new. Inject the package's contracts/services via constructor injection so tests can swap implementations. Where the package offers a fake or an in-memory driver, prefer it; otherwise bind a stub in a test service provider.
• Keep configuration in config/. Publish the config file once and drive environment differences through env() keys referenced from that file, not by editing vendor defaults. This keeps upgrades diff-friendly.
• Feature-test the integration, not the package. Your tests should assert your application's behaviour around the package's boundary (job dispatched, record written, response shaped). The package's own internals are its test suite's responsibility.
• Composer hygiene on deploy. Commit composer.lock, deploy with composer install --no-dev --optimize-autoloader, and re-run php artisan package:discover (or optimize:clear then config:cache) as part of the release step.

Gotchas and Tips

• Constraint resolution confusion. A Laravel 13 app with an older 2.x constraint will usually fail at composer update rather than at runtime. If you see an unexpected failure, run composer update "<vendor>/<package>" --with-dependencies -W and read the conflict output rather than deleting the lock file.
• Published config goes stale. The package merges its own defaults, but a previously published config/<package>.php shadows new keys added in later releases. After upgrading, diff the published file against the vendor stub and merge manually — new options silently default otherwise.
• Discovery and config caching. In production, always run php artisan config:cache and php artisan package:discover after a version bump. A stale bootstrap/cache/packages.php is a common cause of "class not found" that only appears on the deployed environment.
• Queue workers and long-running processes. If the package registers listeners, jobs, or singletons, restart workers (php artisan queue:restart) and Octane/Horizon on deploy; a code-only rollover leaves old code in memory.
• PHP version is the real gate. Laravel 13 raises the platform requirement; check composer check-platform-reqs on the target host/container before assuming a Laravel 13 upgrade is complete.
• Extension points. Override package behaviour by binding your own implementation to the package's interface in a service provider registered after the package provider, or by using the package's documented extension hooks — avoid subclassing internals, which is where upgrades break.
• Debugging. Start with php artisan about to confirm the detected framework and package versions, then check the package's log channel and storage/logs/laravel.log. If behaviour changed only after the upgrade, diff the published config and re-run with config:clear before suspecting the package itself.