Client Laravel Package

Product Decisions This Supports

• Build vs. buy for image/media infrastructure: Still supports outsourcing image storage, transformation, and CDN delivery to Rokka.io rather than building an in-house pipeline. The 1.22.0 release strengthens the "buy" case slightly: cache purging, alias management, metadata reads, and billing visibility are exactly the operational tooling a product team would otherwise have to build around a raw upload/transform API.
• Media-heavy roadmap features: Unchanged applicability — UGC, product catalogs, avatars, CMS media libraries, marketplace listings, travel/real estate imagery, responsive delivery across web and mobile. Alias support and metadata retrieval now make CMS-style and merchandising workflows (stable asset references, editorial metadata surfaced in admin UIs) more feasible without custom glue.
• Cache invalidation as a product capability, not a footnote: The previous assessment flagged cache invalidation as a risk to handle manually. 1.22.0 adds deleteSourceImageCache, deleteStackCache (including whole-organization purge), and alias-cache deletion. This turns "how fast can we correct a bad image?" from a custom-work item into a supported API call — relevant to brand-safety, legal takedowns, and content correction SLAs.
• Vendor exit and data portability: downloadSourceImagesAsZip (up to 300 images per request) provides a documented bulk egress path. That materially de-risks the lock-in argument and supports a credible rollback plan in the vendor decision.
• Cost governance: User::getBilling enables usage/cost dashboards and budget alerts inside internal admin tooling. This converts image spend from an invoice surprise into a monitored product metric — useful for finance partnership and for triggering the "optimize transformations" backlog item.
• Platform upgrade forcing function: 1.22.0 is a breaking bump — PHP ^8.2 and Guzzle ^7.4.5 / psr7 ^2.4.5 — dropped PHP 8.0/8.1 and Guzzle 6. If the product runs older runtimes, adopting or upgrading this package now implies a platform upgrade, which is a roadmap and resourcing decision, not just a dependency bump.
• Operational configuration as code: setOrganizationOptions (full replace) plus the existing single-option setter supports environment-parity and IaC-style management of org settings across staging/production.
• Use-case fit: Unchanged — strongest where the team lacks image-pipeline expertise and needs global delivery plus dynamic transformations quickly; weak where images are simple, low-volume, or must remain self-hosted.

When to Consider This Package

Consider it when:

• Rokka.io has already been selected or is a serious candidate as the image CDN/transformation vendor.
• The backend is PHP 8.2+ (hard requirement as of 1.22.0) with Guzzle 7.4.5+; teams on PHP 8.0/8.1 must scope a runtime upgrade first.
• The backend needs server-side upload, transformation, deletion, metadata, alias, and cache-purge operations against Rokka.io — 1.22.0 now covers all of these without hand-rolled HTTP calls.
• The product needs dynamic resizing, cropping, format negotiation, and CDN delivery without owning that infrastructure.
• You need a supported invalidation path for corrections, takedowns, or editorial replacements, and want it behind a vendor API rather than bespoke scripts.
• Cost observability matters: billing endpoints let you instrument spend before it becomes a surprise.
• The team can wrap the SDK behind an internal image-service adapter and accept a small official vendor client rather than a Laravel-native package with service providers, config publishing, and Blade helpers.
• Time-to-market and reduced infrastructure ownership outweigh keeping the pipeline fully in-house.

Look elsewhere when:

• No Rokka.io vendor decision has been made. Compare Cloudinary, imgix, Cloudflare Images, Bunny, Fastly IO, and self-hosted options (Intervention Image, Glide) before defaulting here.
• The platform is pinned below PHP 8.2, or the upgrade cost is disproportionate to the image roadmap. Note this is a hard break, not a soft deprecation.
• Laravel-native ergonomics, first-class Laravel documentation, or a large ecosystem are hard requirements. This remains a vendor SDK with very low adoption signals (6 stars, 0 dependents); vendor status and active maintenance are the mitigations, not community support.
• Images must be processed and stored entirely in-house, or data residency/processing restrictions are prohibitive.
• Needs extend into rich DAM, AI tagging, moderation, or marketing asset workflows.
• Cache purging is a core requirement but the budget cannot absorb paid features — stack cache purge is explicitly billed, and cache-miss behavior affects render freshness guarantees.
• Simple image needs make a SaaS image CDN hard to justify on cost or complexity.

Release-specific caveats to raise in due diligence:

• The keepHash option on setDynamicMetadata / deleteDynamicMetadata prevents hash churn (nice for late metadata fixes and stable URLs) but means downstream caches — CloudFront, memcached, browsers — serve stale renders until explicitly invalidated. It is mutually exclusive with deletePrevious and throws LogicException if both are passed. Product implication: any UI exposing "edit metadata without changing the image URL" needs a paired invalidation story.
• Endpoint migrations (copySourceImage to POST, getSourceImagesWithBinaryHash to the documented path form) preserve signatures and behavior; internal API consumers should not notice. Treat as safe.
• signUrlOnServer exists, but UriHelper::signUrl() remains preferable for most cases since it signs locally without a network round trip. Architect for the local path to avoid latency and availability coupling.
• PHPUnit 11 / #[DataProvider] migration affects only the package's own tests, plus added MockHandler coverage of the new methods — a positive maintenance signal, not a consumer concern.

How to Pitch It (Stakeholders)

For executives: This is the official PHP client for Rokka.io, a managed image CDN and transformation service. It lets us ship responsive images, dynamic crops, and optimized formats by buying image infrastructure instead of building it. The 1.22.0 release is a maturity signal: it adds cache purging, asset aliasing, metadata access, bulk export, and billing visibility — the operational controls that make a vendor bet survivable rather than just functional. Two things to weigh: the release is a hard platform bump requiring PHP 8.2, and stack cache purging is a paid feature. The strategic upside is faster media feature delivery and lower infrastructure ownership; the residual risks are usage-based cost growth and a small ecosystem. Recommend a time-boxed pilot with a documented exit path — the new bulk-export capability makes that exit path concrete.

For engineering: Plan the runtime upgrade before adopting 1.22.0 — PHP ^8.2 and Guzzle ^7.4.5/psr7 ^2.4.5, dropping 8.0/8.1 and Guzzle 6. Keep the SDK behind an internal image-service interface so the vendor remains replaceable. Use the new purge endpoints (deleteSourceImageCache, deleteStackCache, alias-cache deletion) as the single invalidation primitive rather than ad-hoc scripts. Prefer UriHelper::signUrl() over signUrlOnServer unless you specifically need server-issued URLs. Treat keepHash as a deliberate, documented trade-off — it silently risks stale CDN and browser caches, so pair it with explicit invalidation and make it opt-in at the call site. Pin the client, verify the changelog cadence, add integration tests around upload/transform/alias/purge flows, and secure API credentials. Do not assume Laravel conventions: no service provider, config publishing, or Blade integration.

For product and finance: This unlocks media-heavy features with less custom infrastructure and now gives us built-in levers for corrections and takedowns (cache purge), stable asset references (aliases), cost dashboards (billing API), and data egress (ZIP download). Costs still scale with image volume, transformations, and paid purge features — model expected traffic, transformation volume, and invalidation frequency before committing. Run a time-boxed pilot against at least one alternative vendor, confirm SLA, data-processing terms, and purge pricing, and define measurable adoption or rollback criteria up front.