Eloquent Hashids Laravel Package

Getting Started

The 9.0 release is a compatibility release — its headline change is Laravel 9 support — so treat "getting started" as an upgrade path rather than a greenfield install.

1. Confirm your constraint. Run composer require <vendor>/<package>:^9.0 and verify Composer resolves against your framework version. v9.0 signals alignment with Laravel 9's dependency floor (PHP 8.0+, Symfony 6 components). If you are still on Laravel 8, do not assume 9.0 is a drop-in; check whether the maintainer ships a parallel 8.x line, otherwise pin the last release that declared Laravel 8 support.
2. Check the manifest first. Open the package's composer.json and read require / require-dev. That single file tells you more about upgrade risk than the release note: it reveals the minimum laravel/framework and illuminate/* versions, whether Flysystem 3 is required (a common Laravel 9 break), and whether PHPUnit 9 is pinned.
3. Let discovery do its job, then verify. Laravel's package auto-discovery should register the service provider and any facades. Run php artisan about (or php artisan package:discover on older skeletons) and confirm the provider appears. If the package predates discovery or lists providers conditionally, add it to config/app.php explicitly.
4. Publish and diff config. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" then diff the published file against the package's own copy under vendor/. Laravel 9 packages often renamed or re-nested config keys; a stale published config silently overrides new defaults.
5. Run migrations in a scratch database. php artisan migrate --pretend first to see the SQL, then for real against a disposable schema. Laravel 9 introduced anonymous class migrations and changed default morphs()/id() column behaviour — older published migrations can produce unexpected index or bigint definitions.
6. First real use case: pick the package's most-read code path (a typical read/query, then a write) and exercise it in php artisan tinker before touching your application code. This isolates "package is broken on Laravel 9" from "my integration is wrong."

Implementation Patterns

Pin the major, float the patch. Use "^9.0" rather than "9.0.*" so compatibility fixes land automatically, but keep the major pinned — a version-number jump that tracks the framework major is a maintainer signal that breaking changes ship with majors.

Isolate the package behind a thin adapter. Wrap the package's facade or client in a small application-level service (e.g. App\Support\XyzClient) that you bind in a service provider. This is the highest-value pattern for any third-party package: when the next Laravel major arrives, you change one class instead of grepping callsites. It also makes the package mockable in tests without Facade::shouldReceive everywhere.

Testing integration. In phpunit.xml, ensure APP_ENV=testing and that the package's provider is loaded. Prefer RefreshDatabase with an in-memory SQLite connection for speed, but keep at least one test against your production engine — Laravel 9's Doctrine DBAL 3 upgrade changed several change() and column-introspection paths, and SQLite hides those differences. Use Http::fake() rather than the deprecated assertDeleted-era helpers if the package makes outbound calls.

Configuration over code. Drive environment-specific behaviour (credentials, endpoints, queue names, table prefixes) through the published config file plus env() at the config layer only. Never call env() from application code — it returns null once config:cache has run, and that failure mode is invisible until production deploy.

Queue and event integration. If the package dispatches jobs or events, decide deliberately whether they should run in your queue and on which connection. Override the connection in the config file rather than editing vendor code, and register listeners in your own EventServiceProvider so the dependency direction stays one-way.

Scheduled work. If the package exposes a sync or cleanup command, schedule it in app/Console/Kernel.php (or routes/console.php on newer skeletons) with withoutOverlapping() and onOneServer() where appropriate — the package will not schedule itself.

Upgrade workflow for the 9.0 jump. Create a branch, bump the constraint, run composer update <vendor>/<package> --with-dependencies, then run your full suite and composer outdated --direct. Read the maintainer's changelog across every release between your old version and 9.0, not just the 9.0 entry — the release note here is a summary, but intervening minors may carry deprecations that became removals at the major.

Gotchas and Tips

"Laravel 9 compatibility" is under-specified — go read the diff. A one-line release note is not a changelog. Before adopting, compare the composer.json of the prior release with 9.0's, and skim the commit log between tags (git log v8.x..v9.0 --oneline on the package repo). Framework-major bumps routinely smuggle in Symfony 6, Flysystem 3, and PHP 8 typing changes that break runtime behaviour without appearing in the notes.

Laravel 9's own removals will bite you, not the package. Common casualties when upgrading the surrounding app: $dates on models (use $casts), str_*/array_* global helpers (use Str:: / Arr::), the assertDeleted family in tests, Route::redirect's default status change (301 → 302), and Flysystem 2 → 3 adapter signatures. If something "broke with the package upgrade," it usually broke with the framework upgrade that came with it.

Facade aliases drift. Check extra.laravel.aliases in the package manifest against what your code imports. Auto-discovery only registers what the manifest declares; hand-registered aliases from a previous version can now point at a renamed or removed class and will fail only when that line executes.

Config caching masks stale defaults. After upgrading, run php artisan config:clear && php artisan config:cache. A published config from the old version merged over new defaults is the single most common "the package ignores my setting / the package's new feature doesn't work" cause. Diff before you assume a bug.

Migration drift. If you republished migrations, Laravel keys them by filename. Renamed or re-timestamped migration files from the package will either re-run or be skipped depending on the migrations table contents. Inspect php artisan migrate:status for rows the package owns before and after the bump.

Check the supported-version matrix, not just the number. The major version tracking the framework major is a convention some maintainers follow and others abandon. Verify the package's CI matrix or README badge — a package at 9.0 may still support Laravel 8, or it may have dropped PHP 7.4 with no mention in the note.

Extension points beat forks. Before patching vendor code, exhaust the package's documented hooks: bound interfaces in the container, Macroable traits on facades/builders, config-driven class resolution (e.g. 'driver' => env('PKG_DRIVER', 'default') with a custom driver you supply), and event listeners. Container binding a custom implementation of the package's contract is the sanctioned override path and survives composer update; a fork does not.

Debugging a silent failure. When the package misbehaves, escalate in this order: (1) config:clear / cache the config, (2) confirm provider discovery, (3) Log::debug the resolved config from a booted provider, (4) php artisan vendor:publish --force a fresh config into a scratch copy to compare, (5) drop to the underlying client/adapter directly in Tinker to determine whether the failure is in the package or its integration. Laravel Telescope or a query log will show you the actual SQL the package emits — often the fastest way to see a Laravel 9 schema mismatch.

Watch for the next major now. A 9.0 that exists solely to track Laravel 9 tells you the maintainer's release cadence is framework-coupled. Expect a 10.0 shortly after Laravel 10 and budget for it; if that cadence is not acceptable, that is a stronger argument for the adapter pattern above than any specific bug.