Statamic Es Laravel Package

Getting Started

• Install with composer require <vendor>/<package>; v1.0.1 adds Laravel 5 (illuminate/support ^5.x) compatibility, so confirm your composer.json constraint resolves to ^1.0.1 and not a cached 1.0.0 (composer update <vendor>/<package> --with-dependencies).
• Look first at the package's composer.json (require/autoload), then its service provider. On Laravel 5.5+ package discovery registers it automatically; on 5.0–5.4 you must add the provider to config/app.php under providers and any facade to aliases.
• Publish assets/config before your first call: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (add --tag=config to scope it). Check config/<package>.php for connection, driver, or queue settings that default to something you do not want in production.
• First use case: instantiate through the container (app(Client::class) or the facade) inside a small artisan command or php artisan tinker session to verify credentials/endpoint resolution before wiring it into a controller. This isolates "package not working" from "my application code is wrong".
• Check the changelog/UPGRADE notes for the 1.0.0 → 1.0.1 delta — a support-version bump can carry silent dependency constraint changes (Guzzle, Symfony components), which matter more than the headline.

Implementation Patterns

• Bind once, inject everywhere. Resolve the package's main class from the container in a constructor (or use the facade) rather than calling new in controllers — this keeps config overrides and test doubles working.
• Wrap in your own service class. Put the package behind a thin application-level class (App\Services\...) that your controllers/commands depend on. When v1.x later renames a method or the client signature shifts, you change one file.
• Config over code. Prefer publishing and editing the config file plus .env keys over hardcoding values; keep per-environment credentials in env() and cache with php artisan config:cache in deploy steps (re-run after any publish).
• Queued jobs for anything remote. If the package makes HTTP/API/queue calls, dispatch jobs and use retryUntil/backoff; keep the call site synchronous only for read paths in request flows with tight timeouts.
• Test with fakes, not the network. Swap the underlying client in the container or use Laravel's Http::fake() / Bus::fake() in feature tests; assert on your service class rather than the package internals so package upgrades don't break the suite.
• Version pin deliberately. With only a support-matrix change in 1.0.1, pin "^1.0.1" (or exact 1.0.1) and run the suite on both your minimum and current Laravel 5.x minor before rollout.

Gotchas and Tips

• Stale installs after a support bump. If composer update reports nothing to do, your root composer.json may pin ~1.0.0 in a way that excludes 1.0.1 — check with composer why-not <vendor>/<package> 1.0.1.
• Provider not registered on 5.0–5.4. Package discovery did not exist before 5.5; symptoms are "Target class [...] does not exist" or facade "Class not found". Add both provider and alias manually, and clear caches after editing config/app.php.
• Cached config and routes. php artisan config:clear and route:clear after publishing config or changing env values; a cached config file can make the package appear to ignore new settings.
• Silent default fallbacks. Most packages fall back to a null/sync/default driver when config is missing rather than throwing — verify the resolved config with php artisan tinker --execute="dump(config('<package>'));" rather than assuming.
• Dependency drift from the Laravel 5 constraint. illuminate/support: ^5.x may pull older Symfony/Guzzle versions into a shared app; run composer outdated and the full test suite, and watch for conflicting constraints on packages you also use.
• Extension points to prefer. Config file, container bindings, and published views/translations are the stable seams; extending package classes directly or overriding vendor files is the first thing to break on a minor release.
• Debugging ladder: resolve from container → check config → check provider registration → check network/credentials → only then read package source. Log with the package's own channel/driver setting if it exposes one, so its internal errors surface alongside your app logs.