Search Bundle Laravel Package

Getting Started

Because 2.0.0 shipped as a major version bump with an empty changelog body, treat the upgrade as a re-onboarding rather than a patch. The first hour should be spent reading source, not writing features.

1. Pin and inspect. Require ^2.0 explicitly (composer require vendor/package:^2.0) and open the tagged diff (git log --oneline v1..v2 or the GitHub compare view) before running composer update. In a major release with no notes, the diff is the changelog.
2. Re-publish assets. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --force for config, then publish migrations separately so you can read them before they run. Diff the published config against your committed copy — renamed or removed keys are the most common silent break in a major.
3. Verify discovery. If the package uses auto-discovery, run php artisan package:discover and confirm the provider and any facades/aliases registered. If you manually list providers in config/app.php, check the class name and namespace still exist.
4. Look first at: src/ root (contracts and the service provider tell you the public API surface faster than docs), config/*.php (every key is a supported extension point), and the package's own tests/ (they encode the intended usage better than README snippets, which often lag a major release).
5. First use case. Do not start with the flagship feature. Wire the smallest end-to-end path — instantiate the main class via the container, run one call, assert the result in a feature test — so configuration failures surface in isolation rather than tangled with business logic.

Implementation Patterns

Resolve through the container, never new. Bind the package's contract in a service provider and inject it. This is the single pattern that makes 2.0.0 upgrades survivable: if the concrete class moves or is split, only the binding changes.

// App\Providers\AppServiceProvider::register()
$this->app->bind(
    \Vendor\Package\Contracts\Client::class,
    fn ($app) => $app->make(\Vendor\Package\Client::class)
);

Wrap the package behind your own thin adapter. A App\Services\PackageGateway with three or four methods means the rest of the codebase never imports the vendor namespace. When 3.0 lands, you edit one file.

Drive behaviour from config, not from calls. Anything the package exposes as a config key — drivers, endpoints, retry counts, queue names — belongs in config/ (with env fallbacks) rather than as a hardcoded argument. This is what makes staging/production divergence testable.

Isolate side effects in jobs. If the package dispatches HTTP calls, writes files, or talks to a third party, call it from a queued job with $tries, $backoff, and failed() defined. Retries at the package layer and retries at the queue layer compound — pick one.

Feature-test at the boundary. Use RefreshDatabase, the package's fake/Http::fake() equivalent if provided, and assert on your adapter's output rather than internal package state. Test the failure path (Http::fake with a 500, or the package's exception class) as deliberately as the happy path — major versions frequently re-typed exceptions.

Staged rollout for the major. Ship 2.0.0 to a branch, run the full suite plus one manual smoke test of each integration point, then merge. A major with no notes has no migration guide; your test suite becomes that guide.

Gotchas and Tips

• Config cache first, always. php artisan config:clear before debugging anything. A stale bootstrap/cache/config.php will make a renamed 2.0 key appear to still work in one environment and fail in another.
• Publish tags have changed before now. Try --tag=package-config and --tag=package-migrations explicitly; if the tag is wrong, vendor:publish exits 0 and silently copies nothing. Confirm files actually landed.
• Migration ordering. New migrations in a major often reference columns added by an earlier one in the same release. Run php artisan migrate --pretend first and read the SQL.
• Version constraints in transitive deps. If another package requires ^1.0, Composer may resolve to a partial upgrade or conflict. Run composer why-not vendor/package 2.0.0 before assuming the bump is safe.
• PHP and Laravel floor changes. Majors routinely raise php and illuminate/* minimums. Check composer.json in the package directly — this is the break that bites CI but not local dev.
• Debugging: add a temporary Log::debug() inside the package's entry point via a local path repository override rather than editing vendor/ (which composer install will erase). Or use php artisan tinker to app()->make() the class and inspect state directly.
• Extension points, in order of stability: config keys → contracts you can rebind → published views/translations → macros on a facade (if offered) → events dispatched by the package. Prefer the leftmost option that solves the problem; the rightmost is the most likely to vanish in a minor release.
• Keep an upgrade note in your own repo. Because upstream shipped 2.0.0 with no release notes, record what you changed, what broke, and why. Your future self is the only changelog this release has.