Statamic Api Select Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and confirm Laravel's package auto-discovery picks up the service provider (php artisan package:discover --ansi). If the package predates auto-discovery or disables it, register the provider manually in config/app.php.
• Publish what the package exposes before writing any code:
  • php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=config, --tag=migrations, --tag=assets if tags are defined).
  • Check vendor/<vendor>/<package>/README.md and composer.json first — at 1.0.0 the documented surface is the contract, everything else is internal.
• Run php artisan migrate only if migrations were published; a brand-new "addon" may ship none, so verify the database/migrations directory in the package before assuming schema changes.
• First use case: treat 1.0.0 as a single vertical slice. Identify the one entry point the package advertises (a facade, a contract bound in the container, an artisan command, or a Blade component), wire it into a scratch route or tinker session, and confirm you get the expected output before integrating it into real code.
• Because this is an initial launch, budget time for source reading. Open src/ and locate:
  • the service provider's register() vs boot() split,
  • any bind/singleton calls (these define your extension points),
  • the config file's default keys.

Implementation Patterns

• Resolve through the container, not new. Prefer constructor injection of the package's contract or concrete class over instantiating directly; this keeps your code swappable and testable when the package's API shifts in 1.x.
• Config-first configuration. Copy published config into config/<package>.php and read values via config() rather than mutating package internals. Commit the config file so environment differences are explicit per-env in .env.
• Facade usage in views/controllers only. If the package ships a facade, use it at the edges (controllers, Blade, commands) and inject the underlying class in services and jobs — facades hide dependencies and make unit tests brittle.
• Wrap third-party calls behind your own thin adapter. Even at 1.0.0, put the package behind a small interface in your app (App\Contracts\...) so a future breaking change is a one-file edit, not a grep across the codebase.
• Event-driven integration. If the package dispatches events, listen rather than fork. Register listeners in EventServiceProvider and keep side effects (notifications, logging, cache busting) out of the package's request path.
• Queue long-running work. Any package operation that hits the network or does heavy I/O should be dispatched from a job, not inline in a request — this also gives you retries and observability for free.
• Testing pattern. In feature tests use RefreshDatabase if migrations ship; in unit tests bind a fake/mock of the package contract via $this->app->instance(...). Assert on your adapter's behaviour, not on package internals, so tests survive minor releases.
• Version pinning. In composer.json, use a caret constraint (^1.0) only after you've read the changelog policy; for a first release with unknown velocity, a tighter 1.0.* pin plus scheduled composer outdated checks is safer.

Gotchas and Tips

• Discovery and config caching. After install or upgrade run php artisan package:discover and php artisan config:clear. A stale bootstrap/cache/packages.php is the most common cause of "class not found" or "config key missing" on a fresh 1.0.0 install.
• Config merge semantics. Published config files are not updated by composer update — new keys added in a patch release will silently fall back to package defaults. Diff the package's config/ against yours on every upgrade.
• Migration publishing collisions. If migrations are published to the host app, they become yours; package upgrades cannot alter them. Prefer --tag=migrations deliberately and note the decision in your upgrade runbook.
• Zero-to-one version risk. 1.0.0 signals API stability intent, but the initial release surface is unproven. Expect deprecations and potential breaking changes in 1.x minors; subscribe to the repo's releases and read UPGRADING.md if present before bumping.
• Debugging. Start with php artisan about, then composer show <vendor>/<package> to confirm the installed version, then dump() the resolved config. If a binding misbehaves, app()->make() inside tinker isolates whether the problem is registration or your call site.
• Extension points to prefer. Service provider bindings, published config, and events are stable hooks. Subclassing package classes or overriding Blade views via vendor:publish --tag=views is fragile — published views are copies that will drift from upstream.
• Logging and failures. Confirm the package's exception types before catching broadly; catching \Exception around package calls will mask config errors during rollout. Log the package version alongside the error for reproducible bug reports.