Console Laravel Package

Getting Started

This release is a compatibility bump: the package now declares support for Laravel 8. That is the first thing to verify before anything else, because on a Laravel 8 app the package simply will not install if its composer.json still caps illuminate/* at ^7.0.

Minimal steps:

1. Confirm the runtime: Laravel 8 requires PHP ^7.3, so check php -v and your composer.json platform config before adding the dependency.
2. composer require <vendor>/<package>:^0.3 — if Composer resolves against laravel/framework:^7.x you are on the old constraint and the tag is not the problem, the lockfile is. Run composer why-not <vendor>/<package> 0.3.0 to see the conflicting requirement.
3. Let package discovery do its work. There is no need to register the service provider manually unless you have "extra": {"laravel": {"dont-discover": [...]}} in your app's composer.json. After install, php artisan package:discover should list it.
4. Check for publishable assets: php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>". If the package ships a config file, publish it and commit it — reading config at runtime through config('...') after php artisan config:cache will silently return null if the file only exists inside vendor/.
5. First real use case: take the smallest end-to-end path — instantiate the package's entry point through the container (not new), run it once from php artisan tinker, then move it into a queued job so you exercise the same code path production will use.

Where to look first in the repo: composer.json (constraints and the extra.laravel block), the service provider's register()/boot() methods, and the tests/ directory to see which Laravel and Testbench versions the maintainer actually runs against. The Testbench constraint is the honest signal of Laravel 8 support — a package claiming ^8.0 support but testing on orchestra/testbench:^5.0 is only half-migrated.

Implementation Patterns

Constraint pinning per app version. If you maintain multiple apps across Laravel 7 and 8, pin the package with a version range that matches each app (^0.2 on 7, ^0.3 on 8) rather than relying on Composer to pick. The 0.x version number signals the maintainer has not committed to semver stability, so a floating ^0.3 is acceptable but a floating * is not.

Resolve through the container. Bindings registered by the service provider are the intended integration surface. Type-hint the package's contracts in your controllers, jobs, and listeners rather than referencing concrete classes; when the package changes a constructor between 0.x releases, only your AppServiceProvider binding needs editing.

Wrap it in your own adapter. Given the 0.x stability, put a thin application-level class in front of the package (e.g. App\Support\SomethingGateway) that your domain code calls. This costs one file and turns a breaking 0.4 release into a single-file change. It also gives you an obvious place to add logging and retries.

Config over code for anything tunable. Publish the config and treat the package's own defaults as documentation. Keep environment-specific values in config/ reading from env(), and call config:cache in your deploy pipeline so a missing published config fails loudly in staging rather than in production.

Queue the heavy paths. If the package performs I/O — HTTP calls, file writes, external API syncs — dispatch it from a job with $tries and backoff set explicitly. Laravel 8's job batching (Bus::batch()) is a natural fit for fanning the package's work out across records, and it gives you catch/finally callbacks for partial-failure reporting that you would otherwise hand-roll.

Test against the real container. Use orchestra/testbench:^6.0 for a Laravel 8 package-integration test suite, or in an application test just use the normal RefreshDatabase + Http::fake()/Queue::fake() stack. Assert the container binding resolves, not that a specific class name exists — that keeps the test green across renames.

Feature-flag the rollout. On the first Laravel 8 app, ship the integration behind a config flag or a dedicated queue so you can disable it without a redeploy if the compatibility bump turns out to be shallow (see gotchas).

Gotchas and Tips

"Laravel 8 compatible" does not mean "tested against Laravel 8." A one-line changelog entry is a claim, not evidence. Before committing, check the CI matrix in the repo, or run the package's own test suite locally on Testbench 6. If the maintainer only widened the constraint, subtle breakage in framework internals is possible but unlikely — the risky areas are anything touching the container, the auth guard, or model serialization.

Laravel 8 moved models to App\Models. If the package ships migrations or publishes models that reference App\User, the generated foreign keys or relationship target classes may point at a namespace that no longer exists in a default Laravel 8 app. Inspect any published migration for hardcoded model paths and fix the $table/foreignId targets before running migrate.

Class-based factories. Laravel 8 replaced the global factory() helper with Illuminate\Database\Eloquent\Factories\Factory and the HasFactory trait. If the package's test helpers or seeders call the old factory(App\X::class) string form, those calls will break on 8 even though the package installed fine. This is the most common source of "it installed but the tests explode."

composer.lock conflicts are the number one install failure. If composer require reports a conflict against laravel/framework, run composer why-not <vendor>/<package> 0.3.0 rather than downgrading Laravel. The usual culprit is a transitive dev dependency still pinned to ^7.0 — --with-all-dependencies (-W) fixes it, but check what else moved before you commit the lockfile.

Package discovery cache. After composer update on a running app, bootstrap/cache/packages.php can hold a stale provider list. php artisan package:discover or composer dump-autoload clears it. Symptom: Target class [...] does not exist on a package that is demonstrably installed.

Config cache hides unpublished configs. If config('vendor-package.key') returns null locally but works after php artisan config:clear, the config was never published and the package's own default file is not being merged the way you assumed. Publish it.

PHP 8 deprecations surface at 0.x. Laravel 8 runs happily on PHP 8.0/8.1. If you deploy on 8.1, watch for Return type ... should either be compatible with ... or the #[\ReturnTypeWillChange] attribute should be used notices from the package's collection/iterator implementations. They are notices, not fatals, but they will flood logs.

Extension points to prefer. The service provider is the sanctioned place to extend() or rebind; most 0.x packages expose a container binding or a config-driven driver list specifically so you do not subclass. Check boot() for $this->app->bind/singleton and $this->mergeConfigFrom before writing a subclass — subclassing an unstable 0.x API is the fastest way to break on the next release.

Pin and watch. On 0.x, read the diff between tags before bumping. Set Dependabot/Renovate to open PRs rather than auto-merge for this dependency, and require CI to pass on both the Laravel 7 and Laravel 8 jobs before the bump lands.