Searchable Laravel Package

Getting Started

Version 1.10.5 is a compatibility release: it adds Laravel 5.5 support. There are no documented breaking changes, so treat this as a drop-in upgrade rather than a re-evaluation of the package.

1. Upgrade the constraint — pull the patch line rather than a floating version:

   composer require vendor/package:"^1.10"
   

2. Let auto-discovery do the work. Laravel 5.5 introduced package auto-discovery, and 1.10.5 is the release that opts in. After composer update, confirm the provider is registered without touching config/app.php:

   php artisan package:discover
   

   Look for the package in bootstrap/cache/packages.php. If it is there, remove any manual providers / aliases entries you were carrying from Laravel 5.4 — leaving them in place is harmless but will mask discovery problems later.
3. Clear caches after upgrading, especially if you had a cached config from the previous version:

   php artisan config:clear && php artisan cache:clear
   

4. First use case: publish the config file, set the one or two values you actually need via .env, and resolve the package from the container in a single endpoint or artisan command to prove the wiring works before rolling it across the codebase.

If you are on Laravel 5.4 or earlier, skip this version's auto-discovery benefits — you still register the provider and alias manually, but nothing in 1.10.5 should break you.

Implementation Patterns

Resolve from the container, not the facade, in application code. Facades are fine in controllers and Blade, but constructor-inject the underlying contract in services, jobs, and listeners. This keeps your code testable and means a future major version swapping the facade name won't ripple through your domain layer.

Bind once in a service provider. If you wrap the package (recommended for anything beyond a single call site), create a thin adapter and bind it in AppServiceProvider::register(). Your application then depends on your interface, and the package becomes an implementation detail you can swap or fake.

Configure through env, publish only what you change. Publish the config with the package's publish tag, then delete or comment out every key you aren't overriding. Republishing on upgrade becomes a diff you can actually read instead of a merge conflict.

Testing. Laravel 5.5's container helpers make this cheap:

$this->instance(Contract::class, $fake);
// or, for facades:
PackageFacade::swap($fake);

Prefer instance() for constructor-injected dependencies and swap() only when the facade is genuinely being used. For package-level work, use Orchestra Testbench and register the provider explicitly in getPackageProviders() — Testbench does not exercise auto-discovery the same way a full app does, which is a common source of "works in the app, fails in the suite" bugs.

Defer the provider if it is heavy. If bootstrapping registers routes, migrations, or listeners you don't need on every request, implement DeferrableProvider so it only resolves when something actually asks for it. This is worth measuring before and after — the win is real on large apps, invisible on small ones.

Queue and event payloads. If you dispatch jobs containing package objects, keep the serialized payload small and prefer passing scalars/IDs. Package internals that look serializable often aren't stable across a patch release.

Gotchas and Tips

• Auto-discovery is silent when it fails. Nothing warns you if extra.laravel is malformed — the class simply isn't registered and you get a "target class does not exist" error much later. After upgrading, verify with php artisan package:discover and check bootstrap/cache/packages.php directly.
• Config caching bites on upgrade. php artisan config:cache snapshots the config file at that moment. If 1.10.5 added or renamed config keys, a stale cache will silently serve the old shape. Always config:clear after any package update, and re-run config:cache in deploy scripts after composer install.
• Manifest cache in CI. bootstrap/cache/packages.php is generated. If your deploy pipeline copies a built artifact, run package:discover as part of the build, or you'll ship a manifest referencing paths that don't exist.
• Version pinning. ^1.10 is right for now, but be deliberate: a * constraint on a package still in the 1.x line will eventually pull a minor release with deprecations. Pin the minor, review the changelog on upgrade.
• Alias collisions. If you keep a manual aliases entry alongside auto-discovered aliases, the manual one wins and can point at the wrong class after a namespace change. Pick one mechanism.
• The release note is one line. "Laravel 5.5" tells you it's a compatibility bump, not what else changed. Before rolling to production, diff the published config and skim the commit list on the tag — patch releases sometimes carry small fixes that the note omits. If you're coming from 1.9.x, republish the config to a temp path and diff rather than overwriting.
• Extension points to know before you need them: the container binding (swap implementations for testing or multi-tenancy), driver/managers if the package exposes them, and macros if it wraps a facade. Knowing these exist saves you from forking the package when requirements shift.
• Debugging checklist when something resolves to null or the wrong instance: confirm the provider is in packages.php → confirm config is not cached → confirm your .env keys are spelled exactly as the config expects (env() returns null silently on typos) → check whether a deferred provider is being resolved before the app is fully booted.