Placid Laravel Laravel Package

Getting Started

Install the package and its config:

composer require placidapp/placid-laravel
php artisan vendor:publish --tag=placid-config

Add your API token (from https://placid.app → API) to .env:

PLACID_API_TOKEN=your-token-here

The package is a thin Laravel wrapper around the Placid REST API: a service provider that binds a client into the container, a Placid facade, and a small config file (base URL + token). There is no database, migrations, or UI — everything else lives in your Placid dashboard.

Where to look first:

1. config/placid.php — confirm the key names your version registered (token, base_url); the env var name varies slightly between releases, so match the config file rather than guessing.
2. The package source src/ — a handful of methods that map 1:1 to Placid endpoints (createImage, getImage, etc.). Read it before trusting docs.
3. The upstream Placid API docs — the package mirrors the API, so the API reference is the real manual.

First use case — dynamic Open Graph / social card:

1. Create a template in the Placid dashboard, name its layers (e.g. title, subtitle, background), copy the template UUID.
2. Generate from Laravel:

use Placid;

$image = Placid::createImage([
    'template_uuid' => 'your-template-uuid',
    'layers' => [
        'title'    => ['text' => $post->title],
        'subtitle' => ['text' => $post->excerpt],
        'background' => ['image' => $post->hero_image_url],
    ],
]);

// $image contains a hosted URL you can persist on the model
$post->update(['og_image_url' => $image['image_url'] ?? $image->image_url]);

Treat the exact response shape as something to dd() once — the SDK may return an array or a small value object depending on version.

Implementation Patterns

Wrap the facade in a domain service. Don't scatter Placid:: calls through controllers. Create App\Services\SocialImageGenerator that owns template UUIDs, layer mapping, and error handling. This keeps tests simple and makes it trivial to swap to raw Http::withToken() later if the package lags the API.

Keep templates in config, not code. Map each "kind" of image to a template UUID in config/placid.php or a dedicated config/templates.php:

'templates' => [
    'og'      => env('PLACID_TEMPLATE_OG'),
    'podcast' => env('PLACID_TEMPLATE_PODCAST'),
],

Then Placid::createImage(['template_uuid' => config('templates.og'), ...]). Rotating a template becomes an env change, not a deploy.

Queue bulk generation. Image rendering is I/O-bound and rate-limited. For anything beyond single requests, dispatch a job per item and throttle it:

class GenerateCard implements ShouldQueue
{
    use InteractsWithQueue, Queueable;

    public function middleware(): array
    {
        return [new RateLimited('placid')];
    }

    public function handle(SocialImageGenerator $generator): void
    {
        $generator->generate($this->post);
    }
}

Define the placid limiter in a service provider to match your plan's concurrency.

Prefer Placid → S3 transfer over proxying bytes. If your template supports it, use the API's transfer option so Placid uploads directly to your bucket. Otherwise download once and store locally; never make the Placid URL your permanent storage.

Use webhooks for slow renders. Pass webhook_success_url in the create payload, register a route, and update the model when the callback fires. This avoids tying up PHP workers on multi-second renders and is the only practical path for video/PDF if your plan includes them.

Cache by payload hash. Renders are deterministic given the same layers. Hash the template UUID + layer payload, store the resulting URL in cache or a column, and skip regenerating. Invalidate when the source content changes — usually by hooking model saved events.

Test by faking the facade. In feature tests:

Placid::shouldReceive('createImage')
    ->once()
    ->andReturn(['image_url' => 'https://cdn.example/test.png']);

Pair this with a contract test (a single un-faked call in a nightly/sandbox job) so you notice when the real API diverges from your mock.

Webhook route hardening. Webhooks are unauthenticated by default; gate them on a shared secret in the URL path or query string that you compare with hash_equals(), and reject payloads whose template_uuid isn't one you own.

Gotchas and Tips

Last release 2022 — assume drift. The wrapper predates newer Placid endpoints and parameters. If you need something the package doesn't expose, don't fight it: call the API directly with Http::withToken(config('placid.token'))->post('https://api.placid.app/api/rest/images', $payload). Keep the facade for the common paths and drop to HTTP for the edges.

Laravel version constraints. Check composer.json before installing on Laravel 10/11. If it's not declared compatible, either fork with a widened constraint or rely on composer require --ignore-platform-reqs in a dev branch while planning a manual migration. A 2022 package with 58 stars is unlikely to get a timely compatibility PR.

Facade faking is all-or-nothing. Placid::shouldReceive() mocks the entire facade, so any unmocked method throws. If your service calls several endpoints, either mock every one or inject the underlying client and mock that instead.

Config cache surprises. php artisan config:cache snapshots env values. Changing PLACID_API_TOKEN in .env on a cached production box has no effect until you re-run the command.

Template layer names are case-sensitive and silently forgiving. A typo in a layer key typically produces an empty or default layer rather than an error. When a render looks wrong, dump the payload and diff it against the layer names in the Placid editor before suspecting the package.

Rate limits and 429s. Placid enforces plan-level quotas. In queued jobs, catch 429 specifically and release() with backoff rather than failing; in sync requests, surface a meaningful error to the user instead of a stack trace.

URLs expire; files don't. Placid-hosted image URLs are CDN-backed and can rotate. Persist either the downloaded file or a copy you control. If you store the raw URL, add an og_image_refreshed_at column so you can detect staleness.

Webhooks need public reachability. Local development requires ngrok, Expose, or similar. Add the tunnel URL to the webhook_success_url at call time — don't hardcode it, or staging callbacks will hit production.

Custom fonts and static assets are template-level. You can't upload a font per request. If a client needs a new typeface, that's a dashboard change, not a code change — factor it into estimates.

Log the request ID. Placid support will ask for it. Wrap API calls in a small middleware or helper that catches the SDK's exception, logs the payload (redacting the token) and any response id, then rethrows a domain-specific exception.

Extension point: because the package is just a service provider binding, you can override the binding in AppServiceProvider with your own class implementing the same method signatures. That's the cleanest way to add retries, logging, or a mocked transport without forking.