Laravel Translatable Laravel Package

Getting Started

1. Install and pin. composer require vendor/package:^6.0 — commit the lock file. Because 6.0.1 lands in the 6.x line, confirm your composer.json still satisfies the package's PHP and illuminate/* constraints before anything else; a major bump usually raises the floor on both.
2. Read three files, in this order: README.md (quickstart), UPGRADING.md / CHANGELOG.md (what 6.0 broke vs 5.x, and what 6.0.1 patched), and the package's src/*ServiceProvider.php (register() + boot() tell you what is bound, what is published, and what is auto-discovered).
3. Publish and diff. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" then immediately php artisan config:clear. Read the published config/package.php top to bottom — v6 defaults are the most common source of "it silently behaves differently" reports.
4. First use case: a throwaway route or php artisan tinker session. Exercise one complete write → read → delete cycle against a scratch model/record before wiring the package into a real feature. In v6 the value is usually in changed defaults rather than new API, so you want to see actual output, not just a green test suite.

Implementation Patterns

Keep package calls behind a thin app-level seam. Wrap the facade/client in a small App\Support\… service and inject that. You get one place to change when 6.1 renames something, and your tests stop needing the package's fakes everywhere.

// app/Services/Billing.php
final class Billing
{
    public function __construct(private \Vendor\Package\Client $client) {}

    public function charge(Order $order): Receipt
    {
        return $this->client->charge($order->total, $order->currency);
    }
}

Prefer constructor injection in domain code, facades in controllers/console commands. Facades are convenient at the edges and painful in the middle — Facade::shouldReceive() in a domain test is a smell that you should have injected the underlying contract.

Hook events instead of overriding internals. Most mature Laravel packages dispatch lifecycle events; listen in EventServiceProvider (or AppServiceProvider::boot() in Laravel 11) rather than subclassing a package class. Subclassing is the first thing to break on a major release.

Publish migrations, then own them. Run the package's migrations locally to see the schema, but ship edited copies in database/migrations with a timestamp after the package's. Never let a package migration be the only record of a data-shape decision in production.

Queue discipline. If the package dispatches jobs: check $tries, $timeout, $backoff, and whether it implements ShouldBeUnique. Set queue:restart in your deploy script — a 6.x upgrade that changes job payloads will explode on workers still holding serialized old-payload jobs.

Testing.

• RefreshDatabase + the package's own testing helpers if it ships them.
• Http::fake() when the package talks to an API; Event::fake() when you care about what it emits, not what it does.
• Freeze time (Carbon::setTestNow()) for anything expiry/token/retry related — v6-era packages increasingly depend on absolute timestamps.
• Add a test that asserts your config file still contains the keys the package actually reads; that catches upgrade-silent-default drift cheaply.

Multi-connection / multi-tenant. If you run more than one DB connection or a tenancy package, resolve the package's connection from config rather than letting it default to database.default. Do this the same day you install it — retrofitting is far worse than setting it up front.

Gotchas and Tips

• After any vendor:publish or upgrade: php artisan optimize:clear. Config cache is the number one cause of "the upgrade did nothing" and its mirror image, "the upgrade broke everything."
• 6.0.1 is a patch, not a migration guide. Treat 6.0.0 as the breaking release and 6.0.1 as "the yanked-tag fix." Re-read the 6.0.0 upgrade notes even if you jumped straight to 6.0.1 — the breaking changes are still in there.
• Auto-discovery conflicts. If you registered the provider manually in 5.x and it's auto-discovered, you'll get double registration: duplicate routes, duplicate listeners, doubled queue jobs. Grep config/app.php and bootstrap/providers.php for leftovers.
• Facade alias collisions. A Package alias that shadows an app class surfaces as a baffling "method does not exist" hundreds of lines away. Check config/app.php aliases after upgrading.
• Silent default changes. Diff the published config against the package's config/ source after every minor. Keys that changed default are usually the ones nobody documents loudly.
• Debugging order: php artisan about (env, cache, driver) → tinker (is the binding resolvable?) → Log::debug() inside a listener → only then the package source in vendor/. Reading vendor source first is how afternoons disappear.
• Extension points, in order of safety: container bindings for interfaces → published config → published views/translations → custom drivers registered via the package's manager → macros → subclassing (last resort).
• Deprecations: run your suite with deprecation reporting on (<phpunit displayDetailsOnPhpunitDeprecations="true"> on PHPUnit 10+) right after upgrading. The warnings you see now are the 7.0 breakages you avoid later.
• Rollback plan. Pin 6.0.1 exactly in composer.json (not ^6.0) for the first week in production, and keep the previous lock file on the branch. A patch release that regresses is rare but not mythical, and composer require vendor/package:5.x must be a one-command escape hatch.