Client Laravel Package

Technical Evaluation

• Architecture fit: Unchanged in essence: rokka/client remains a thin official PHP API client for Rokka.io, not a Laravel package, and still fits as an infrastructure adapter around an external image-processing/CDN service. Release 1.22.0 significantly widens the surface area of that adapter — aliasing, source-image renaming, cache purging, ZIP export, user metadata, stack-option introspection, server-side URL signing, billing, and organization options — which makes Rokka more viable as a full media-lifecycle backend rather than just a render-URL generator. It is a worse fit if we only need simple resizing, since the wrapper now has more capability to (selectively) expose.
• Integration feasibility: Still feasible via Composer with a Laravel wrapper (config, credentials, singleton binding, ImageTransformer-style contract), but the wrapper's scope grows. The new alias model (SourceImageAlias) and alias CRUD imply a mapping/naming convention we must own in application config. listStackOptions can drive validation of stack option payloads; getUserMetadata/getUserMetadataField enables metadata-driven logic but needs a caching and typing layer. No auto-discovery, facade, or Laravel config exists in 1.22.0. The PoC must now also cover alias lifecycle, cache purge, and ZIP download against a non-production org.
• Technical risk: Adoption risk is materially unchanged in kind — still a small ecosystem footprint — but maintenance risk is lower: 1.22.0 adds MockHandler-based test coverage, migrates legacy endpoints (copySourceImage, getSourceImagesWithBinaryHash) to documented routes, and modernizes the toolchain (PHPUnit 11). The offsetting risks are now breaking platform constraints: PHP 8.0/8.1 support and Guzzle 6 are dropped (requires PHP ^8.2, guzzlehttp/guzzle ^7.4.5, guzzlehttp/psr7 ^2.4.5). This can collide with older Laravel applications and with other packages pinning Guzzle 6 or PSR-7 v1. Additional risks: destructive operations (deleteSourceImageCache, deleteStackCache with *) are one config typo from a full-org purge and are paid features; keepHash creates deliberate cache-coherence risk; signUrlOnServer adds a network round-trip where local UriHelper::signUrl() would do.
• Key questions: Is our runtime on PHP ≥8.2 and Guzzle ≥7.4.5, and can we resolve PSR-7 v2 across the dependency graph? Is Rokka strategic versus Cloudinary, imgix, or self-hosted? What do the SLA, pricing, and rate limits look like — and which 1.22.0 features are gated behind paid tiers (cache purge, ZIP, signing)? Do we need aliasing and rename semantics in the product, or are hashes sufficient? Who is authorized to call destructive cache-purge methods, and how is that guarded? How do we prevent keepHash from shipping stale renders to users? Which PHP/Laravel versions must our wrapper support, and does dropping PHP 8.1 force an upgrade elsewhere?

Integration Approach

• Stack fit: Install via Composer and isolate the client behind an application service/interface; use Laravel DI, not static calls. Store org/API key and stack names in env/config. Add a thin RokkaConfig/policy layer that whitelists which API methods the application may call — critically, restrict cache-purge, rename, and billing calls to privileged services rather than exposing them broadly. Do not leak Rokka concepts (aliases, stack options, hashes) into controllers or Blade; expose view models/helpers for URLs.
• Migration path: Upgrade the wrapper in lockstep with 1.22.0 before starting new integration work, since the PHP 8.2 / Guzzle 7.4.5 floor is a hard gate. Then adopt features incrementally: start with existing upload/stack/URL/delete flows, then add aliasing for stable, human-readable asset references where the product benefits, then metadata reads, and only later cache purging and ZIP export. For local-processing replacement, keep the legacy pipeline for published assets while new originals go to Rokka stacks; backfill originals asynchronously if alias/metadata history is needed. The endpoint migrations (copySourceImage, getSourceImagesWithBinaryHash) are behavior-preserving, so no call-site changes are required — but verify by contract test.
• Compatibility: Confirm PHP ^8.2 in the app and CI matrix, guzzlehttp/guzzle ^7.4.5, guzzlehttp/psr7 ^2.4.5, and that no transitive dependency pins Guzzle 6 or PSR-7 v1. Check Laravel version compatibility: Laravel 10 on PHP 8.1 is blocked by this release, so an app upgrade may be a prerequisite. Pin the client version in composer.json (caret constraint plus lockfile), and run composer why-not/conflict checks in CI. Add mocked-client unit tests plus opt-in contract tests against a non-production Rokka org; verify CDN URL patterns, alias resolution, and purge propagation.
• Sequencing: 1) Dependency/upgrade spike: PHP 8.2, Guzzle 7.4.5, PSR-7 v2, Laravel version. 2) Credentials/upload/transform/render/delete spike. 3) Build config, service provider, interface, policy layer, and test doubles. 4) Integrate one low-risk image type behind the abstraction. 5) Add alias management (if justified), metadata reads, retries, observability, fallback. 6) Introduce cache purge and ZIP export only after an authorization and audit design exists. 7) Review cost tier coverage for paid features, SLA, and runbook before broad rollout.

Operational Impact

• Maintenance: Better maintained than the prior baseline — test coverage is now explicit, legacy endpoints are removed, and the toolchain is current. We still own the Laravel adapter, contract tests, and upgrade path. Enforce a version pin and an upgrade cadence, because this release proves the package will drop PHP/Guzzle majors on its own schedule; our wrapper must be able to follow or deliberately lag. Keep the interface provider-agnostic to preserve exit options. Expect recurring work as we decide which of the new APIs (aliases, metadata, billing) to expose.
• Support: Rokka supports the service; package-level community support remains thin, so internal ownership is unchanged. New runbook items are required: alias naming conventions and conflicts, cache-purge authorization and blast radius (* org-wide purge), ZIP download for large asset sets, and metadata schema expectations. Notify the team that signUrlOnServer exists but is usually the wrong choice versus local signing — document the decision to prevent accidental latency.
• Scaling: Offloading processing and delivery still scales better than local image workers. New scaling concerns: cache-purge rate and propagation delay (CloudFront/memcached/browser), ZIP downloads for up to 300 images (bandwidth and memory on our side), metadata fetch volume (cache it; do not call per request), and billing API polling limits. Watch transformation/storage costs, API rate limits, cache hit ratio, and whether paid features (purge, ZIP, signing) push spend beyond forecast.
• Failure modes: Rokka API outage, expired credentials, upload timeouts, invalid stack operations or payloads, URL/hash mismatches, CDN cache delays, quota/cost overruns, and dependency incompatibility (a PHP 8.1 host or Guzzle 6 pin will simply fail to install). New failure modes: stale renders caused by keepHash — metadata updates won't bump hashes, so browsers and CDNs serve old images until manual invalidation; accidental org-wide cache purge via deleteStackCache('*'); alias collisions or dangling aliases after rename/delete; LogicException from passing both keepHash and deletePrevious. Mitigate with authorization and confirmation guards on destructive calls, retries/backoff, circuit breaking, health checks, placeholder/original-image fallback, and alerting on error rates and quota.
• Ramp-up: Code ramp-up stays low; domain ramp-up is now moderate-to-high because the API surface roughly doubled — aliases, source-image naming, metadata, stack options, cache semantics, signing modes, and billing. Budget an additional spike for the PHP 8.2/Guzzle upgrade if the app isn't already there, plus training and a runbook covering the new operations and their paid/irreversible nature. A safe production rollout is likely a few developer-days for the wrapper, plus dependency upgrade effort, plus one to two weeks for validated migration depending on the media surface.