Content Api Bundle Laravel Package

Getting Started

This is a pre-1.0 package (0.1.x), so treat the public API as unstable and pin an exact version in composer.json ("vendor/package": "0.1.3") rather than floating on ^0.1.

Minimal steps:

1. composer require vendor/package and confirm the service provider is auto-discovered (check bootstrap/providers.php / config/app.php if it isn't).
2. Publish the config: php artisan vendor:publish --tag=<package>-config, then move credentials into .env — base URL, API key/token, timeout. Never commit the published config with secrets in it.
3. Skim, in this order: the config file (what's tunable), the main client/service class (what verbs and options exist), the facade or binding in the service provider (how it's resolved from the container), then tests/ for executable examples of intended usage.

First use case: a read-then-write round trip. Fetch a resource with GET, mutate a field locally, and send the whole representation back with PUT — the flow added in v0.1.3. Getting this working end-to-end against a sandbox/staging endpoint proves auth, serialization, and error handling in one pass.

Implementation Patterns

Resolve through the container, not the facade, in domain code. Constructor-inject the client into a small repository or service class (BillingGateway, CrmClient). Facades are fine in controllers and artisan commands, but injecting makes the gateway swappable in tests and keeps a single seam for retries and logging.

Wrap every endpoint in a named method. Don't scatter $client->put('/users/'.$id, $payload) across the app. One method per remote operation gives you one place to change when the upstream API drifts — which it will, given the 0.x version number.

Model PUT as full replacement. The v0.1.3 addition is the verb, not a merge. Build the payload from a complete DTO (or a freshly fetched resource) rather than a sparse array of changed fields, because a strict PUT endpoint will treat omitted keys as "clear this". If you only have diffs, PATCH is the semantically correct verb — verify whether the package exposes it before assuming.

Use PUT for safe retries. PUT is idempotent, so it composes well with queue jobs and retry middleware: re-dispatching a failed SyncProfile job won't create duplicates the way a retried POST can. Keep POST for creates and PUT for updates keyed by a client-known ID.

Test with the framework's HTTP fake. If the package is built on Laravel's Http client, Http::fake() plus Http::assertSent() gives you fast, network-free tests — assert the verb explicitly ($request->method() === 'PUT') and assert the body, since a wrong-verb regression is exactly the class of bug this release fixes. If it wraps Guzzle directly, bind a mock handler in the container instead.

Keep payload shaping out of the package layer. Map Eloquent models or form-request data to an explicit array/DTO at the boundary. This is where you normalise dates, booleans, and nulls, and it's the layer you'll change when the upstream contract changes.

Gotchas and Tips

• PUT bodies are JSON by default in Laravel's HTTP client. If the target API expects application/x-www-form-urlencoded, you need ->asForm(); sending JSON to a form endpoint usually produces a confusing 400 or a silently empty payload. Check what the package does before debugging your own array.
• _method=PUT is a Laravel routing convention, not an HTTP client feature. Method spoofing applies to HTML forms hitting your own routes. It does nothing for outbound API calls — use the real verb.
• Full-replacement semantics are the top support ticket generator. A PUT built from a partial array can null out unrelated fields server-side. Always fetch-merge-send, or confirm the endpoint accepts sparse updates.
• 0.x means minor bumps can break. 0.1.3 → 0.2.0 may remove methods without a deprecation cycle. Read the changelog before every composer update and keep a pinned version in CI.
• Verify PATCH support explicitly. The release note mentions PUT only. If your domain needs partial updates, check the client's method list or open an issue — don't assume parity with the full verb set.
• Debug by inspecting the outgoing request, not the stack trace. Wrap the client's transport (Guzzle middleware or Http::globalRequestMiddleware) to log method, URL, and body with auth headers redacted. Most failures here are auth, content type, or payload shape — not the package.
• Set timeouts and retries in config, once. A default-infinite timeout will hang queue workers. Configure a sane timeout plus a bounded retry (2–3 attempts, backoff) at the client level, not per call site.
• Extension points worth knowing: if the client is Macroable, add project-specific verbs (->macro('upsert', ...)) instead of forking. Custom headers, base URI overrides, and token refresh usually live in a config array or a service-provider binding — that's the right place for tenant-specific credentials in multi-tenant apps.
• Watch the response contract, not just the verb. Error mapping (404 vs 422 vs 5xx) determines whether your job retries or fails permanently; make sure the package surfaces status codes rather than throwing a generic exception.