Laravel Identicon Laravel Package

Getting Started

v2.1 is a compatibility release: the headline change is Laravel 8 support, so the first move is a version-constraint bump rather than a code change.

1. Confirm the install path. Require ^2.1 explicitly (not ^2.0) so Composer resolves the branch that carries the Laravel 8 constraint:

   composer require vendor/package:^2.1
   

   If you were previously pinned to ^1.x or ^2.0, check composer why-not vendor/package ^2.1 before upgrading — an old transitive dependency is the usual culprit when resolution fails on Laravel 8.

2. Verify discovery. Laravel 8 still honours package auto-discovery. After composer update, run php artisan package:discover --ansi and confirm the provider appears. If the package ships a facade, check it's aliased in config/app.php only if you're on a non-standard bootstrap.

3. Publish and diff config. This is the step people skip:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config
   

   Publish into a scratch directory first and diff against your existing config/package.php. A minor bump can add keys with defaults that silently differ from the package's internal fallbacks.

4. Run migrations if the package ships them. php artisan vendor:publish --tag=migrations then php artisan migrate. On Laravel 8, verify the published stubs use the class-based migration format (return new class extends Migration) — older anonymous-closure stubs still work but will not match your other migrations.

5. First use case. Pick the lowest-risk entry point: a read-only query or a single facade call in a tinker session (php artisan tinker) before wiring it into a controller. That tells you whether config, container bindings, and credentials are correct in one step.

Where to look first in the repo: composer.json (constraints and extra.laravel discovery block), the service provider (what's bound as singleton vs. fresh), and the UPGRADING/CHANGELOG files for anything the release notes omitted.

Implementation Patterns

Resolve from the container, don't new it. Bind once and inject:

public function __construct(private PackageContract $package) {}

If the provider registers it as a singleton and you need per-request state, use app()->forgetInstance() or request a fresh instance — don't mutate a shared singleton.

Wrap third-party calls behind your own interface. This package is a dependency, not a domain concept. A thin adapter means the next major bump (or a swap) touches one class, and it makes the package trivially fakeable in tests.

Config over code for environment variance. Put credentials in config/package.php backed by env(), and keep a single config/package.php per app. Cache-bust awareness: any env() call outside config files returns null once php artisan config:cache runs — a classic Laravel 8 deployment failure.

Queue and job integration. If the package makes network calls, wrap them in a job with $tries, $backoff, and $timeout set explicitly rather than relying on worker defaults. On Laravel 8, use dispatchAfterResponse() for fire-and-forget telemetry-style calls, and Bus::batch() for fan-out workloads — both are stable in 8.x.

Testing pattern. For feature tests, RefreshDatabase plus an explicit fake or a container swap in setUp():

$this->swap(PackageContract::class, new FakePackage());

For package-adjacent unit tests, Orchestra\Testbench version alignment matters: Testbench 6.x pairs with Laravel 8. Mixing Testbench 5.x with Laravel 8 produces confusing container errors that look like package bugs.

Blade and event hooks. If the package exposes events, register listeners in EventServiceProvider rather than in the provider's boot() — it keeps php artisan event:list accurate and makes the wiring greppable.

Gotchas and Tips

• PHP floor. Laravel 8 requires PHP >= 7.3; if CI still runs 7.2 the bump fails at install time, not at test time. Check platform config in composer.json before blaming the package.
• composer update vs. require. Running composer update vendor/package may resolve the constraint without touching the lockfile's other entries; running a bare composer update can drag in unrelated Laravel 8 upgrades. Prefer composer update "vendor/package" --with-dependencies.
• Legacy factories. Laravel 8 split factories into classes. If the package's test helpers or seeders reference the old factory() global, add laravel/legacy-factories as a stopgap and schedule the rewrite — it will not survive Laravel 9.
• Auto-discovery caching. After a version bump, a stale bootstrap/cache/packages.php can mask the new provider. php artisan package:discover or deleting the cache file resolves phantom "class not found" errors.
• Config cache in deploys. The canonical order is config:cache → route:cache → view:cache. Running config:cache before publishing new config keys leaves you with defaults and no error.
• Silent config drift. New minor-version config keys usually have safe defaults, but credential keys sometimes default to null and fail lazily at first call rather than at boot. Assert on required config in a test or in the provider's register().
• Facade vs. injection. Facades resolve at call time; constructor injection resolves at construction. In long-running workers (Octane, queue workers) that difference decides whether you get fresh state or a stale singleton.
• Debugging. php artisan about (8.x) gives a fast environment snapshot; php artisan tinker plus app(Vendor\Package\PackageServiceProvider::class) confirms which provider instance is loaded when you have duplicates from a manual registration plus auto-discovery.
• Extension points. Prefer the package's published interfaces and events over subclassing its concrete classes — subclasses break on minor bumps that add constructor arguments, whereas interface implementations survive.
• Pinning. With a minor release this narrow, pin ^2.1 and let patch releases flow; add composer outdated --direct to CI so the next compatibility release surfaces as a PR rather than a surprise.