Laravel Subby Laravel Package

Getting Started

This release (v7.0.4) is a compatibility patch: it adds Laravel 10 support to the existing v7 line. There are no API changes, no new config keys, and no deprecations — so if you are already on v7 with Laravel 9, treat this as a drop-in bump. If you are on Laravel 10, this is the first v7 release you can install, which makes the version constraint the single most important detail of the upgrade.

Minimal path:

1. composer require <vendor>/<package>:^7.0.4 — pin the floor at 7.0.4, not ^7.0. Earlier 7.0.x releases will not resolve against laravel/framework:^10.0.
2. Confirm the platform: Laravel 10 requires PHP 8.1+, so check composer.json require.php before you start.
3. Publish what the package ships: php artisan vendor:publish --provider="...ServiceProvider" (config, and migrations if applicable), then php artisan migrate.
4. Open the published config file first — it is the fastest map of the package's behaviour and the thing you will actually touch day to day.
5. First real use case: wire it into a single model or controller and exercise it through php artisan tinker before touching the wider app. Verifying resolution and one happy-path call isolates install problems from integration problems.

Implementation Patterns

Resolve from the container, never instantiate. Laravel packages in the v7 era almost universally register a singleton and often a facade. Type-hint the contract or facade in constructors and let the container wire it. new-ing the concrete class bypasses config, caching, and any decorators the package applies.

Wrap it behind your own boundary. The single most valuable pattern for a package on a fresh major: put a thin app-level service (or repository) in front of it. Your controllers depend on your class, the package is called in exactly one place, and the next major bump becomes a one-file change. This matters more for v7 because 7.0.4 is the first Laravel 10–compatible cut — you should assume more 7.0.x patches are coming and keep the blast radius small.

Config-driven, config-cached. Publish the config, commit it to the repo, and set environment-specific values in .env. Anything the package reads at boot will be frozen by php artisan config:cache, so deployments need config:cache in the release step, not ad hoc.

Offload slow work to the queue. If the package performs I/O (HTTP, filesystem, image processing, indexing), kick it onto a job rather than calling it in a request. That keeps the Laravel 10 upgrade honest — queue worker restarts (queue:restart) after deploy are part of the same release runbook.

Testing. Use RefreshDatabase and the package's own factories where provided. For the upgrade specifically, add one smoke test that boots the package and asserts a resolved instance is not null — it catches service-provider and auto-discovery regressions instantly.

Upgrade workflow. Branch, bump the constraint, run the full suite, then check the changelog for 7.0.0 → 7.0.4 as a block rather than patch by patch.

Gotchas and Tips

• The version floor is the gotcha. ^7.0 will happily install 7.0.0 on Laravel 9 and then fail to resolve on Laravel 10. Require ^7.0.4 explicitly and note why in a comment or the PR description.
• Auto-discovery vs. manual registration. If you have a legacy config/app.php providers array entry, you may end up with the provider registered twice after upgrading. Remove the manual entry and rely on discovery unless the README says otherwise.
• config:clear when behaviour looks stale. Ninety percent of "the package ignores my config" reports are a cached config from a previous deploy or a stale bootstrap/cache.
• Migration collisions. Fresh publishes can collide with previously published migrations. Check the migrations/ directory before running vendor:publish on an existing app; on a fresh install it is a non-issue.
• Debugging: php artisan about and php artisan tinker with app()->bound(...) will confirm registration faster than reading stack traces. If a facade throws "class not found," the provider is not booting — check discovery and composer dump-autoload.
• Extension points: container bindings in a AppServiceProvider::register() are the cleanest way to swap an implementation without forking. Prefer published config + bindings over editing vendor files.
• Laravel 10 deprecations are transitive. The package now supports Laravel 10, but your app's other dependencies may not. Bump this package alone first, verify, then move the rest — do not upgrade framework and five packages in one commit.