Enum Field Laravel Package

Getting Started

• Install with a pinned constraint — a first release means the API surface is unproven. Use composer require vendor/package:^1.0 and check the resolved version in composer.lock; avoid dev-main in anything production-bound.
• Before writing code, open the package's composer.json and confirm illuminate/support and php constraints match your app (Laravel 10/11/12, PHP 8.2+). Mismatches surface later as confusing container or signature errors.
• Check whether the provider is auto-discovered (extra.laravel.providers). If so, do not also register it in config/app.php. Confirm with php artisan about or php artisan package:discover.
• Publish what the package ships, using tags:
  • php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
  • or --tag=config / --tag=migrations individually. Read the published config end-to-end before editing; commit it so environment drift is visible.
• If there are migrations, publish and run them (php artisan migrate) in a local branch first; inspect table names for collisions with your schema.
• Where to look first, in order: README → the ServiceProvider (what is bound, what is registered, which singletons exist) → the config file (every knob the author intended you to touch) → any Facade class (the public API in one screen).
• First use case: resolve the package's main class out of the container in php artisan tinker (app(MainClass::class)) and exercise the smallest happy-path call. This catches missing config, missing credentials, and registration problems in under a minute.
• Immediately convert that tinker session into one feature test so the happy path is pinned before you build on it.

Implementation Patterns

• Resolve from the container; never new the package's classes. Constructor injection in your own classes keeps you config-compliant and mockable.
• Put a thin adapter of your own between your app and the package (App\Services\FooClient wrapping the package). When 2.0 lands — or the package is abandoned — one class changes instead of forty call sites.
• Prefer DI over facades in classes; facades are fine in Blade and one-liners. If you use facades heavily, confirm the facade class carries @method docblocks so static analysis and IDEs keep working.
• Keep configuration env-free outside config files. Any env() read in application code is a landmine once php artisan config:cache runs in deploy.
• Treat any package singleton (HTTP client, connection, token, cached catalogue) as suspect in queue workers and Octane. Verify with a two-job test or a two-request run under octane:start before trusting it.
• For queue/event integration: test with QUEUE_CONNECTION=sync first to force errors into your face, then move to database/redis. Ensure anything the package dispatches is serializable.
• Testing patterns:
  • If the package ships fakes/mocks, use them; otherwise $this->mock(ClientContract::class, ...) in setUp() before the container resolves the consumer.
  • For network-touching packages, Http::fake() and assert on the recorded request (Http::assertSent) rather than trusting the package's own assertions.
  • Bind your mock at the interface, not the concrete class, or the package's internal binding wins.
• Wrap network-bound calls in your own timeout/retry policy rather than inheriting the package default — a first release frequently ships an unset timeout.
• Catch package-specific exceptions at your adapter boundary and re-throw as domain exceptions. First-release error messages tend to be terse; centralising the translation makes debugging and future upgrades cheap.
• Deploy checklist: publish+commit config, run package migrations in the deploy step, and clear cached config after any env change (php artisan config:clear locally, cache rebuild in CI/CD).

Gotchas and Tips

• 1.0.0 means SemVer now applies, but the surface is brand new — expect meaningful additions and the occasional behavioural tweak in 1.x. Pin ^1.0, read the changelog before every minor, and record the exact version you shipped with.
• Config-cache trap: env() called from package source outside a config file returns null once config is cached. Symptom is "works locally, breaks in staging/production". Grep the package's src/ for env( to see how exposed you are.
• vendor:publish without a tag publishes everything; publishing twice without --force silently leaves your edited config stale relative to a new default. Diff published config against the package's after upgrades.
• Package migrations can collide with your table names. Check timestamps and table names before running against a shared database; rename via the package's config key if it offers one rather than editing vendor files.
• Double registration: auto-discovery plus a manual entry in config/app.php yields duplicate bindings, duplicate listeners, or doubled event handling. php artisan about shows discovered providers — check there first.
• Tests may hit the real API by default. Guard with a fake in TestCase::setUp() or short-circuit when app()->runningUnitTests().
• Debugging toolkit: the package's own debug flag if present, Log::debug around the adapter call, php artisan event:list, route:list, queue:failed, and about. Most "it does nothing" reports are a provider that never booted.
• Extension points beat forks: if the package binds an interface, rebind your own implementation in a AppServiceProvider rather than patching vendor code — it survives composer update.
• Keep a short internal note of the pinned version, published config diff, and any migrations applied. That note is what makes the 1.1 upgrade a ten-minute task instead of an afternoon.