Statamic Cloudinary Laravel Package

Product Decisions This Supports

• Feature: Offloading image delivery to Cloudinary (transformation, format negotiation, CDN) while keeping Statamic's asset authoring workflow intact — editors still pick assets in the CP, delivery happens through Cloudinary URLs.
• Roadmap: A low-effort path to improve media performance (responsive images, modern formats) without rebuilding the asset pipeline or adopting a full DAM.
• Build vs buy: Leans "buy/assemble" for Cloudinary itself, and "adopt" for the glue. The glue is thin — a converter, a tag, a Blade component, and a config file — so the real decision is the Cloudinary contract, not this package. Treat the addon as a replaceable adapter.
• Risk posture (revised after v1.5.1): The addon is designed to fall back to Statamic Glide when Cloudinary is misconfigured or an asset lookup fails. That fallback was broken in v1.5.0: {{ cloudinary:field }} threw ArgumentCountError and 500'd both when credentials were absent (every tag render) and when a referenced asset was missing or renamed. v1.5.1 fixes both call sites in Tags\Cloudinary::wildcard() and is the first release with any test coverage of that class. Net effect: graceful degradation is still the right de-risking argument, but it is now a verified-this-release property rather than a long-standing one — pin >= 1.5.1 and cover the fallback with a test you own.
• Use cases: Marketing/content sites on Statamic 5 or 6 with heavy image volume, multi-site or multi-locale media needs, teams already paying for Cloudinary, and migrations where you want to trial Cloudinary on a subset of templates (via <x-cloudinary-image /> or the tag) before committing.
• Not supported by this package: No migration tooling for existing asset libraries, no CP-level UI or bulk re-processing, no frontend build pipeline. Any "move 40k assets to Cloudinary" decision is an engineering project this addon does not cover.
• Vendor lock-in is contained: Config-driven URL generation and PSR-4 structure mean swapping back to Glide is a template-level change, which keeps the Cloudinary ROI decision reversible.

When to Consider This Package

Consider it when all of the following hold:

• You are on Statamic 6 with a matching Laravel version. (Statamic ^5.73.11 is still declared, but see the version-confidence caveat below before assuming it works.)
• Cloudinary is already approved (budget, contract, or a pilot), so you are solving integration, not vendor selection.
• You want Cloudinary transformations available both in Antlers/Blade templates (tag) and in Blade components with modest effort.
• You value graceful degradation to Glide over strict failure — good for progressive rollout behind a feature flag or per-template adoption. Note that this now requires v1.5.1 or later; earlier releases can 500 where you expected a Glide fallback.
• Your team can read ~4 PHP files and own the code if needed. This is a small surface area; source review is a realistic onboarding step.

Look elsewhere or plan to fork/vendor it when:

• Adoption risk matters. 7 stars, 0 dependents, and a single active release line is the headline concern. There is no community backstop, so budget for internal ownership.
• Version confidence is required. The declared matrix includes Statamic 5 (Laravel 10/11), but the test harness runs only on Laravel 12 / Testbench 10 with no CI matrix — so Statamic 5 support is asserted, not tested. v1.5.1 makes this worse-looking before it gets better: require-dev had pinned orchestra/testbench ^9, which is uninstallable due to security advisories, meaning no test runner was installable at all prior to this release. If you are on Statamic 5, add a spike plus your own smoke tests before committing.
• Release-process hygiene is a gate. v1.5.1 is a clean, scoped bugfix with explicit "no breaking changes / no config updates" notes and a published root-cause write-up — a positive signal. But it also reveals that a total-failure bug in the documented fallback path shipped in 1.5.0 and survived to a release. Weigh that against the low bus factor.
• You need enterprise-grade guarantees: SLAs, security review artifacts, published changelogs, semantic versioning discipline, or a migration path for existing asset libraries.
• You need Cloudinary features beyond URL generation — upload API, signed transformations, DAM workflows, video, or CP editing experiences. This is a delivery-side adapter only.
• You need a supported frontend pipeline (Vite, responsive srcset generation, blurhash/LQIP placeholders) — those are yours to build.
• Your organization prohibits single-maintainer dependencies in the render path.

Recommended adoption posture: vendor or fork the package into your codebase at v1.5.1 or later, pin the version, add the missing Laravel/Statamic 5 test run to your CI if you rely on that range, and wrap usage so fallback behavior is covered by a test you own — the v1.5.0 regression is a concrete demonstration of why.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, MIT-licensed open-source connector that lets our Statamic CMS serve images through Cloudinary instead of our own servers. It's narrow in scope — it builds Cloudinary URLs and handles the fallback when Cloudinary isn't available — so the strategic decision is really whether we invest in Cloudinary, not in this package. The upside is faster pages and offloaded image processing; the cost is Cloudinary's subscription plus the engineering time to migrate existing media, which this package does not automate. The main caveat is maturity: it has very low adoption (7 stars, no downstream dependents), and the most recent release fixed a bug where the safety fallback failed outright — which is now fixed and, for the first time, tested. We should plan to own the code rather than rely on a community. Recommended next step is a time-boxed pilot on a single high-traffic template to measure page-speed gains and confirm our Statamic/Laravel version combination.

For engineering: Four files to review — CloudinaryConverter (all parameter translation, centralized by design), Tags\Cloudinary (Statamic tag plus Glide fallback), Components\Image (Blade wrapper), and ServiceProvider (config merge and publish to config/statamic/cloudinary.php). Conventions are documented in AGENTS.md, and there's a Pest suite with AddonTestCase. What changed in v1.5.1: the ArgumentCountError in Tags\Cloudinary::wildcard() is fixed at both fallback sites, Tags\Cloudinary now has its first tests, and the dev toolchain is repaired — require-dev previously pinned orchestra/testbench ^9 (Laravel 11), uninstallable because those releases are blocked by security advisories, so nothing could run the suite. It now runs on Laravel 12. Consequences to plan around: pin >= 1.5.1 (v1.5.0 500s on every {{ cloudinary:field }} without credentials, and on any missing/renamed asset with credentials), treat the declared Statamic ^5 range as untested and add a version matrix to CI, and test the fallback path explicitly — it is the feature that makes a phased rollout safe, and it just shipped broken. Also note composer lint mutates files rather than dry-running. Plan to vendor the package rather than depend on the release line.