Placid Statamic Laravel Package

Getting Started

Install the addon and publish its config:

composer require ritson/placid-statamic
php artisan vendor:publish --tag=placid-config

Then read, in this order:

1. config/placid.php — defaults for headers, timeout, and caching.
2. The README on the repo (short, but the only real docs — 55 stars means no blog posts to fall back on).
3. src/ — the Antlers tag class is the integration surface; skim it before debugging template issues.

First use case: pull a public JSON endpoint into an Antlers view. The tag wraps a request, and the body is exposed as a variable inside the tag pair:

{{ placid:get url="https://api.example.com/posts" }}
  {{ if success }}
    <ul>
      {{ data }}
        <li>{{ title }}</li>
      {{ /data }}
    </ul>
  {{ else }}
    <p>API returned {{ status }}</p>
  {{ /if }}
{{ /placid:get }}

That data / status / success trio is the contract you'll use 90% of the time. Confirm the exact variable names against the README and the tag source — this is a 2021 addon and the docs are thin.

Implementation Patterns

Tag-based GET with query params. Params are passed as tag attributes and forwarded as the query string. Keep a partial per endpoint so templates stay readable:

{{ placid:get url="https://api.example.com/search" q="{ get:q }" limit="10" }}
  {{ data }} ... {{ /data }}
{{ /placid:get }}

Authenticated requests. Don't inline secrets in templates — pull them from config/env and pass through:

{{ placid:get url="https://api.example.com/me" :headers="auth_headers" }}

For anything non-trivial, drop into PHP (a controller, a Statamic action, or a Blade view) and use the placid() helper, which mirrors the same fluent API:

$users = placid()
    ->withToken(config('services.acme.token'))
    ->withHeaders(['Accept' => 'application/json'])
    ->get('https://api.example.com/users')
    ->collect();          // Illuminate\Support\Collection

->json(), ->collect(), ->body(), ->status(), ->successful() and ->failed() are the response accessors; ->response() gives you the raw Guzzle response when you need headers.

POST/PUT from forms. Map submitted fields into the body and branch on success:

{{ placid:post url="https://api.example.com/leads" :body="post_data" }}

Use ->asForm() (PHP) or the equivalent flag when the API expects application/x-www-form-urlencoded rather than JSON.

Caching. Both in-template (cache="3600" style attribute) and in PHP via ->cache(seconds) are available. Cache aggressively for read-only, slow upstreams; skip caching for anything user-scoped unless the cache key includes the user. If you need more control than the package offers, wrap the call in Statamic's {{ cache }} tag or Cache::remember in PHP and let Placid just be the HTTP layer.

Reuse via partials. A partials/api/posts.antlers.html that owns one endpoint, with the caller passing url/params, keeps tag soup out of page templates and gives you one place to change when the upstream changes.

Integration tips. Pair Placid with Statamic collections only when you actually need editorial control — for volatile external data, hitting the API on render (with a cache) is simpler than an importer. If the upstream is unreliable, front it with a scheduled php artisan command that warms the cache, so templates never block on a slow API.

Gotchas and Tips

• Age is the biggest risk. Last release July 2021, no dependents, 55 stars. Expect friction on Statamic 4/5 and Laravel 9/10 — check the composer.json constraints before installing, and be prepared to either pin older framework versions or vendor/fork the addon. Guzzle version conflicts are the most likely install failure.
• No community to lean on. When something breaks, your debug loop is ->response()->getBody() in a tinker session (or a temporary route) — not GitHub issues. Budget for that.
• Error semantics. A 404/500 from the upstream is still a successful HTTP round-trip; branch on success/status, not on whether the tag rendered. Log failed calls server-side rather than exposing upstream bodies to visitors.
• Cache invalidation is manual. Cached responses key off the request; changing a header or token may not bust the cache the way you expect. After rotating credentials, clear the cache explicitly.
• Secrets in templates. Anything in an Antlers file is committed to the repo and visible to anyone with content access. Keep tokens in config/ + .env and pass them in as variables.
• SSRF surface. If URLs come from user input, validate/allowlist hosts. The addon has no built-in allowlist as far as I can tell — enforce it in your own wrapper.
• Timeouts/retries. Defaults are Guzzle's; set a short timeout (3–5s) and a cache in front, otherwise a flaky upstream turns your page render into a 30-second hang. Retries belong in your PHP layer, not in a template.
• Antlers parsing quirks. Attribute values with nested quotes, or arrays rendered from another tag, often need care — test in isolation with a hardcoded URL first, then substitute dynamic values.
• Extension points. You can register your own Statamic tags that call placid() internally, which is the sane way to add logging, retries, or URL allowlisting without forking. That's also your escape hatch if the addon stops working: the placid() helper is a thin Guzzle wrapper, so migrating to raw Http:: calls in a custom tag is a small, well-scoped job.