Laravel Companion Apps Laravel Package

Getting Started

Scope: 2.2.0 is a compatibility release whose only documented change is Laravel 13 support. Treat the day-to-day workflow as unchanged from the 2.x line, but verify the package in a Laravel 13 skeleton before adopting it broadly.

1. Check composer.json requirements for PHP and illuminate/* constraints. Laravel 13 support often implies a newer minimum PHP version.
2. Install or upgrade with composer require <vendor>/<package>:^2.2 in a Laravel 13 app.
3. Look first at the package service provider, config file, and README/UPGRADE notes. The release notes are intentionally narrow, so the package docs remain the source of truth for actual API behavior.
4. First use case: run a smoke test in a fresh Laravel 13 app — publish config if available, clear caches, and exercise the package’s primary entry point (facade, injected service, command, or route).

Implementation Patterns

• Pin to ^2.2 in Laravel 13 projects so compatibility fixes are available without jumping major versions.
• Rely on Laravel package auto-discovery where possible. If the package does not support discovery, register the service provider explicitly in bootstrap/providers.php for Laravel 13.
• Keep package configuration in config/ and environment variables rather than inline overrides. Publish config once, then manage per-environment values through .env.
• In CI, test against both Laravel 12 and 13 if the package supports both. Use a matrix that covers the lowest and highest supported PHP versions.
• If the package publishes migrations, views, or other assets, include vendor:publish in deployment or setup scripts and keep published files under version control where appropriate.
• For application code, prefer dependency injection over facades when testing behavior. Facades are fine for quick integration, but constructor injection makes package services easier to mock.
• If the package exposes events, jobs, or commands, register them through the package’s documented extension points rather than modifying vendor files.

Gotchas and Tips

• Laravel 13 may raise the PHP minimum version. Confirm your runtime and CI images match before upgrading.
• After upgrading, run php artisan optimize:clear and php artisan package:discover to avoid stale config, route, or manifest caches.
• Watch for transitive dependency constraints. A package may claim Laravel 13 support while one of its dependencies still pins older illuminate/* versions.
• Run the package’s own test suite or a representative application smoke test with --prefer-lowest to catch constraint issues early.
• If you use Laravel Octane, verify the package does not retain request state in singletons or static properties.
• Debug discovery issues with php artisan about and by checking bootstrap/cache/packages.php.
• Extension points to review: service provider bindings, config keys, published assets, and any documented macros or custom drivers. Prefer these over subclassing vendor classes.
• Because 2.2.0 is a compatibility-only release, treat any behavior changes as undocumented until verified against the package’s changelog and test suite.