Imgproxy Bundle Laravel Package

Product Decisions This Supports

• Image delivery architecture: transform-on-request vs. pre-generate derivatives. This bundle is the thin integration layer that lets the app emit signed imgproxy URLs instead of running GD/Imagick inside PHP workers or maintaining a batch resize farm. That's a genuine platform decision — it moves CPU/memory cost off the app tier and onto a dedicated service that is cacheable at the CDN edge.
• Build vs. buy vs. self-host for image transformation. The real decision is imgproxy (self-hosted) vs. a SaaS like Cloudinary/imgix. This package is only relevant on the "self-host" branch; it lowers the cost of that branch by removing the need to hand-roll URL signing, option serialization, and Twig/Blade ergonomics.
• Feature roadmap unblocking. Responsive srcset, AVIF/WebP negotiation, focal-point cropping, social/OG image variants, and thumbnail grids for UGC are all cheap to ship once signed-URL generation exists. 0.5.3 adds a watermark option, which pulls a further item into the "cheap" bucket: brand-marking or protecting user-uploaded and marketing imagery no longer requires a separate compositing step in PHP or a design-team export process. Conversely, if this package is not in place, those features tend to get scoped as "image pipeline project" and slip.
• Cost modelling. Per-transformation SaaS pricing scales with page views and variants; a fixed imgproxy instance plus CDN egress does not. The bundle itself is MIT and trivial to swap, so it de-risks the self-host option during evaluation.
• Abstraction boundary hygiene. Because it is a small adapter, it supports a deliberate decision: keep image URL construction behind one service/helper so the transform provider remains replaceable. Treat this as plumbing, not a product differentiator — do not let it leak into domain code.
• Brand/policy enforcement on imagery. Watermarking is a policy lever as much as a visual one (UGC attribution, unpaid-tier asset protection, OG card branding). Deciding whether watermarking is applied at the pipeline layer vs. as a deliberate, per-surface opt-in is a product decision; 0.5.3 makes the pipeline-layer option available, which means someone should own the question rather than defaulting to "we'll add it later in Photoshop."
• Multi-environment / multi-tenant signing. Separate key/salt per environment (and per tenant, if the bundle's config allows it) is an operational decision worth making early rather than retrofitting.

Caveat to raise before anything else: this is a Symfony bundle, not a Laravel package. If the roadmap sits on Laravel, the equivalent decision is "write ~50 lines of HMAC signing + a Blade helper, or use a generic imgproxy PHP SDK" — do not plan around this repo.

When to Consider This Package

Adopt when:

• The application is Symfony 6/7 on PHP 8.x, and imgproxy is already deployed, in procurement, or a serious candidate.
• You need signed URLs (key + salt), sensible processing-option handling, and Twig/controller ergonomics — and you'd otherwise write and maintain that yourself.
• You need watermarking as part of the same transformation pipeline (UGC attribution, tier-based asset protection, branded social/OG cards) and would otherwise bolt on a second compositing path.
• The team is small and prefers a narrow, single-purpose dependency over a full imagine/filter stack (LiipImagineBundle, Glide) that duplicates what imgproxy already does.
• You want the option value of self-hosting without committing engineering time to the signing layer.

Look elsewhere when:

• The stack is Laravel, Slim, or plain PHP — this bundle will not install. Use a generic imgproxy client or hand-rolled signing.
• You need more than URL generation: upload handling, storage abstraction, cache invalidation, media library, or DB-backed asset metadata. This is not a DAM. Watermarking does not change that — you still need somewhere to store the watermark asset and a policy for which URLs get it.
• You need a local-development story without running imgproxy (on-the-fly passthrough or filesystem cache fallback). Verify before committing; if absent, that's real friction for every developer.
• You need rich named filter sets, loaders, and cache resolvers in PHP — LiipImagineBundle has vastly more surface area and community.
• Procurement requires vendor SLA, security review artifacts, or long-term support commitments. At ~11 stars, 0 dependents, and no visible ecosystem, the bus factor is effectively the maintainer's goodwill. One feature commit is a positive maintenance signal but not a support contract. Only proceed if a code read confirms the surface is small enough that forking is a day's work, and you are comfortable owning that fork.

Due diligence checklist (one afternoon): pinned Symfony/PHP version constraints; whether the signing algorithm matches your imgproxy version's key/salt scheme; test coverage; open-issue responsiveness; whether processing options are typed or string-passthrough (the new watermark option is the current test case — check whether it was added as a typed builder method or raw passthrough); and whether the README documents the security model (keep the salt server-side, never expose unsigned URLs). Additionally for 0.5.3: confirm the watermark feature assumes imgproxy's own watermark support (font file present in the imgproxy container, minimum imgproxy version), that it composes correctly with resize/fit options, and that it isn't limited to a single hardcoded position/opacity. If any of that is missing, the watermark gap is yours to close.

How to Pitch It (Stakeholders)

To executives: "We're deciding how the product serves images — avatars, product photos, thumbnails, social previews. Two paths: pay a SaaS per transformation, or run an open-source image server on our own infrastructure. This library is the small, MIT-licensed connector that makes the self-hosted path cheap to try. It is roughly a hundred lines of URL signing and templating — it does not add a vendor, a contract, or a migration. The latest release also covers watermarking, so branding and UGC-protection requirements can ride the same pipeline instead of becoming a separate project. Recommendation: spend a day validating it in a spike; it materially reduces the cost of the self-host option and unblocks responsive images, modern formats, and asset branding on the roadmap."

To engineering: "Thin Symfony bundle around imgproxy: config for endpoint/key/salt, a service that builds signed transformation URLs, and Twig/controller helpers. 0.5.3 adds watermark support as a processing option. It replaces bespoke signing code we'd otherwise own, and it keeps image processing out of PHP-FPM. It is not a media library and not a filter engine — LiipImagineBundle is the alternative if we want transformations in-process. Risks: low community adoption, so budget a code review and assume we may fork; and it is Symfony-only, so it's a non-starter if any service in scope is Laravel. Success criteria for the spike: signed URL generated from a Twig template, served through the CDN, AVIF/WebP negotiation verified, a watermarked variant rendered end-to-end (including confirming the font is baked into the imgproxy image), and a documented local-dev fallback."