Filament Phone Input Laravel Package

Getting Started

Install and verify in one pass. The fastest path to confidence with any Laravel package is a throwaway branch: composer require <vendor>/<package>, then immediately check whether the service provider was auto-discovered (php artisan about prints the discovered providers and their status). If it isn't listed, you're either on a package that predates discovery or you've got a cached manifest — run php artisan package:discover before assuming the package is broken.

Look at these three things first, in this order:

1. config/<package>.php after publishing — php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config. This file is the package author's mental model of the feature surface. Read it top to bottom before reading the README; it tells you what's tunable, what's optional, and which defaults are opinionated.
2. The service provider's register() and boot() — this is where the container bindings, facades, and extension hooks live. Ten lines here save an hour of guessing how to swap an implementation.
3. The package's own tests/ directory — the most reliable documentation of intended usage, and usually more current than the docs site.

First use case to validate: a single end-to-end smoke test in a fresh Laravel app, not your existing one. Existing apps hide integration problems behind pre-existing config, environment differences, and container bindings that accidentally satisfy the package's dependencies. Once that passes, wire it into your real app on a branch and run your existing test suite — regressions from a new provider are usually config or container collisions, and they show up immediately in tests that touch the container.

Implementation Patterns

Resolve through the container, not the facade, in new code. Facades are fine for terse application code, but in services and anything you intend to test, constructor-inject the package's interface or concrete class. This makes $this->swap()-style test doubles trivial and keeps the package a swappable dependency rather than a hard-coded global.

Publish config, then override via env(). The published config file belongs in version control; the values it reads from .env are per-environment. Resist editing the published file to hard-code values — that's how you end up with staging credentials in a config file that someone later commits. If the package's config uses env() calls directly, note that env() returns null once php artisan config:cache has run outside of the config files themselves — a very common production-only break.

Wrap it behind a thin adapter. Even a one-method adapter class (App\Support\FooClient delegating to the package) pays for itself the first time you need to mock it, add logging around it, or migrate off it. This is the single highest-leverage pattern for packages that do I/O — HTTP, queues, storage, search.

Prefer the package's own extension points over subclassing. Most Laravel packages expose a driver/manager pattern (extend(), custom resolvers), events, or macroable classes. Registering a custom driver in a dedicated AppServiceProvider or a small PackageServiceProvider of your own is cleaner than extending a concrete class, because it survives minor-version internals changes.

Handle anything expensive asynchronously. If the package performs network calls, file processing, or bulk writes, push it onto a queue job rather than calling it inline from a controller. Chunk bulk operations — most packages will happily accept a 50k-row collection and then OOM or time out.

Test with the package's fake if it ships one. Package::fake() / ::swap() style helpers exist to keep the suite hermetic. Where they don't exist, bind a test double in the container inside setUp() and assert against your adapter rather than the package internals — asserting on vendor internals makes every patch release a potential test failure.

Gotchas and Tips

• Config caching is the number one production surprise. After publishing config or changing env values: php artisan config:clear locally, and ensure your deploy pipeline runs config:cache after the .env for that environment is in place. Symptom: works in artisan serve, silently uses defaults in production.
• Auto-discovery vs. manual registration. On older Laravel versions (or when dont-discover is set in composer.json), the provider won't load automatically. Check composer.json's extra.laravel.dont-discover array first when a package "isn't doing anything."
• Published migrations collide. Two packages that both publish create_jobs_table, or a published migration timestamped earlier than your existing tables, causes ordering failures on a fresh migrate. Rename the published file's timestamp, and consider --pretend on a scratch database first.
• Facade state leaks between tests. Facades cache the resolved instance for the request/process. If a test swaps a binding, a later test can still hit the old instance — call the package's clearResolvedInstance() or use RefreshDatabase plus a fresh application per test.
• Pin the version, and read UPGRADE.md before bumping. Minor versions of Laravel packages frequently change default config values or drop support for older framework versions. Pin in composer.json and treat upgrades as a deliberate change with the test suite as the gate.
• Debugging the container: php artisan tinker then app()->bound(Vendor\Package\Thing::class) and get_class(app(Vendor\Package\Thing::class)) tells you instantly whether your binding won or the package's. php artisan about confirms provider load order — later providers' bindings win.
• Extension points worth checking for, in order of preference: published config → events dispatched by the package → macroable classes → driver/manager extend() → binding an interface in your own provider → subclassing (last resort).
• Log the package's channel separately. If the package writes to Log::info liberally, give it a dedicated channel in config/logging.php and route it there via a custom handler, otherwise it drowns your application logs.