Rokka Io Api Platform Bridge Laravel Package

Getting Started

This package is a bridge between Rokka.io (an image processing/CDN service) and API Platform: it lets you expose Rokka-rendered image URLs directly on your API resources instead of hand-building URLs or storing derived image paths. Release 1.1.0 is a compatibility release only — PHP 8.*, Symfony 5 and 6 — so treat it as "same feature set, modern runtime floor."

Prerequisites before you install:

• PHP 8.0+ (1.1.0 dropped 7.x support)
• Symfony 5.4 / 6.x components (see the Laravel caveat below)
• api-platform/core 2.6+ / 3.x
• A Rokka account with an organization, an API key, and at least one configured stack (a named set of image transformations, e.g. teaser, hero)

Minimal steps:

1. composer require terminal42/rokka-io-api-platform-bridge
2. Register the bundle (Symfony) — it ships as a Symfony bundle, not a Laravel package.
3. Publish/author the config with organization and api_key, sourced from env (ROKKA_ORGANIZATION, ROKKA_API_KEY). Never hardcode.
4. Look first at the bundle's DependencyInjection/Configuration.php to see the exact config keys, then the service definition that constructs the rokka/client instance, then the attribute/annotation + normalizer that turns a resource property into a URL. The README and src/ are small — read them end to end before writing code.
5. First use case: add a coverImage hash column to an Article resource, annotate the property with a stack name, and confirm GET /articles/{id} returns a Rokka CDN URL instead of a raw hash.

If you are on Laravel: this is where you stop and check scope. API Platform's Laravel integration exists, but this bridge exposes Symfony DI services. You will be wiring it manually in a service provider (see Gotchas) — budget an afternoon, not five minutes.

Implementation Patterns

Config-first, stacks as named constants. Keep stack names in config or a PHP enum, not as string literals sprinkled across resources. Stack definitions are the thing most likely to change (dimensions, formats, quality), and a rename should be a one-line config diff.

Store hashes, render URLs. Persist only the Rokka image hash (plus, if you care about reproducibility, the original source hash and upload metadata) on your model. Let the bridge derive the URL at serialization time. This means changing a stack's options or moving to a different stack is a config change, not a data migration. It also sidesteps the classic trap of storing absolute CDN URLs in the database.

Stack-per-context via serialization groups. Map thumb / teaser / hero stacks to different API Platform serialization groups so list endpoints return small renditions and detail endpoints return large ones. URLs are derived from stored hashes, so exposing image fields on collection endpoints is essentially free — no N+1, no extra queries.

Uploads are your job, rendering is the bridge's. Handle the multipart upload in your own API Platform operation (a custom POST/PUT controller), push the binary through the Rokka client, persist the returned hash, and let the bridge handle representation only. Don't try to make the bridge a media library.

Fake the client in tests. Bind a stub to the Rokka client interface in your test container so feature tests never touch the network. Assert on URL shape (host, stack segment, hash) rather than an exact string — Rokka URLs include stack config that will drift.

Cache hard. Rokka URLs are content-addressed by hash + stack configuration. A stack edit produces new URLs, so long-lived Cache-Control headers and CDN caching are safe and are where most of the perceived performance win comes from.

Decorate, don't fork. The URL-rendering service and the normalizer are the two sensible override points. If you need custom stack parameters per request (e.g. responsive variants), decorate the renderer rather than editing vendor code.

Gotchas and Tips

• It is not a Laravel package. There's no service provider, no config/rokka.php to publish. Under api-platform/laravel you must register the bundle's services manually or wrap it in a thin provider. The 1.1.0 constraint (Symfony 5/6) also means you inherit whatever Symfony components API Platform's Laravel package pulls in — run composer why symfony/http-kernel and confirm there's no conflict before committing to this.
• No migration steps from 1.0.5, but a runtime leap. 1.1.0 adds PHP 8 and Symfony 5/6 support and nothing else. If you were pinned to Symfony 4 / PHP 7.x, the bridge isn't what's holding you back — your whole stack is. The bridge itself needs no code changes.
• PHP 8 type strictness will surface latent bugs. Arguments that were silently coerced under 7.x now throw TypeError. Audit nullable properties on your resources and anything you pass into the Rokka client.
• Credentials fail at request time, not boot time. A missing or wrong API key can still let URL building succeed in some configurations, producing "works locally, 401/404 from Rokka in production." Add a smoke test that actually exercises the client against a known stack.
• Stack name typos don't throw. An unknown stack returns a 404 from Rokka's CDN, not an exception from PHP. Validate stack names against your config enum before they reach the bridge.
• Hashes are immutable. Rokka identifies an image by its content hash; you cannot swap the underlying source after upload — re-uploading yields a new hash. Keep a source_hash column and, if you need reproducibility, an upload history table.
• Serialization groups are the #1 "why is my image missing". If the property's group isn't on the operation, the field silently vanishes. Check the operation's normalization_context first, every time.
• Debugging. The bridge logs almost nothing. Use Symfony's profiler HTTP client panel (or your Laravel HTTP client logging) to see calls to Rokka, and remember that a working URL requires no HTTP call at all — the bridge just composes a string. If the URL looks wrong but no request was made, the bug is in your hash/stack wiring, not the network.
• Extension points worth knowing: the URL renderer, the normalizer, and the DI configuration class. Everything else is thin glue.
• Version pin: ^1.1 is reasonable. There's no 2.x line and the surface area is small, so be prepared to vendor-patch or decorate if you need behaviour the bridge doesn't offer; don't expect frequent releases.