Symfony Number To Words Laravel Package

Getting Started

• Install with composer require <vendor>/<package>; on Laravel 5.5+ the service provider and facade are auto-discovered via extra.laravel in the package's composer.json. Confirm with php artisan about or composer show <vendor>/<package> before debugging anything else.
• Publish assets first, not later: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (add --tag=config to limit scope). Reading the published config file is the fastest way to understand what the package actually does — it documents the real surface area far better than the README.
• Where to look first in the source: src/*ServiceProvider.php (register() shows bindings and singletons, boot() shows routes, migrations, commands, Blade directives), then any Contracts/ directory. That tells you what is swappable and what is hard-wired.
• First use case: wire it into a single console command or a single controller action and assert the output in a feature test. Do not roll it across the app until you've confirmed config resolution, caching, and queue behaviour in isolation.
• If the package ships migrations, run php artisan migrate on a scratch database first and inspect the generated schema — column types and indexes are the most common source of later friction.

Implementation Patterns

• Wrap, don't sprinkle. Put the package behind one thin application-level service (e.g. App\Services\FooService) that you bind in your own provider. Call sites depend on your class, not the vendor's. This is the single highest-leverage decision for a 1.x dependency — it makes an eventual swap or a fork a one-file change.
• Bind contracts, not concretes. If the package exposes an interface, rebind it in your AppServiceProvider::register() rather than resolving the facade everywhere. Facades are fine at the edges (Blade, controllers); constructor-injected contracts are better in domain code.
• Config over code. Anything the package exposes as a config key should be set in config/<package>.php with env() defaults, then overridden per environment. Never edit vendor files, and never call setters at runtime for values that belong in config.
• Push slow work to the queue. Most packages that touch third-party APIs or the filesystem offer a job or an event. Prefer dispatching the package's own job over wrapping a synchronous call in your own — you inherit its retry/backoff semantics, which are usually tuned to the vendor's rate limits.
• Feature-test with its fakes. If the package ships Package::fake() or a HTTP fake integration, use it in the suite; fall back to Http::fake() or container swapping ($this->swap(Client::class, $mock)) otherwise. Assert on your wrapper's output, not on the package's internals.
• Multi-tenant / per-request context. Resolve the package per tenant from a scoped binding ($this->app->scoped(...)) rather than a singleton if config or credentials vary per request.
• Rollout order that works: config published → one feature test green → one real call site → remove the old code path → then delete the old dependency.

Gotchas and Tips

• Config cache is the #1 false alarm. After publishing or editing the config, run php artisan config:clear (and route:clear / view:clear if the package registers routes or views). Deploy pipelines that run config:cache will happily serve the pre-publish defaults.
• Auto-discovery silently off. If the package is in require-dev, or composer dump-autoload was never run after install, nothing registers and the failure looks like a class-not-found rather than a missing provider. Check bootstrap/cache/packages.php.
• Facade alias collisions. Publishing the alias into config/app.php is unnecessary on modern Laravel and will shadow an existing alias. Import the class instead.
• Octane and long-lived workers. Singletons that memoize config, HTTP clients with baked-in auth headers, or stateful builders will leak across requests under Octane/queue workers. Prefer scoped() and reset state in a listener if the package has no reset hook.
• --force is destructive. vendor:publish --force overwrites local edits to published config and migrations. Diff before doing it, and prefer --tag to republish only what you changed.
• Laravel major version constraints. A 1.0.0 tag usually pins an illuminate/support range. Before upgrading your framework, check composer why-not — the package is often the last blocker, and a ^1.0 constraint on the package plus ^11.0 on the framework is the combination to verify first.
• Extension points, in order of preference: (1) rebind a contract in your own provider, (2) $this->app->extend() the resolved instance, (3) a decorator implementing the same interface, (4) fork. Registering your provider before the package's in config/app.php lets you seed values its boot() reads.
• Debugging: php artisan about for discovered providers, php artisan tinker to inspect the resolved binding (app(Foo::class)), Log::debug() inside your wrapper to confirm you are hitting the real implementation and not a cached or faked one.
• 1.0.0 semantics. Treat this as the first stability promise: pin ^1.0, read the changelog for 1.x minors (they should be additive), and expect breaking changes only at 2.0. Anything you cannot express through config or a rebind is a fork risk — note it now rather than after the second call site lands.