Weave Code
Imgproxy Bundle Laravel Package
mezcalito/imgproxy-bundle
A Symfony bundle for integrating imgproxy into your application. Configure endpoints and URL signing, then generate optimized, resizable image URLs for templates and services without embedding image-processing logic in your app.
mezcalito/imgproxy-bundle integrates imgproxy into Symfony applications, providing a clean way to generate secure, signed image URLs for on-the-fly resizing, cropping, and format conversion. Configure your imgproxy endpoint and signing credentials once, then build optimized image URLs from services or templates.
- Signed URLs using configurable HMAC key and salt
- Twig helpers for generating image URLs directly in templates
- Configurable presets for reusable resize, crop, and processing options
- Symfony DI integration with bundle configuration and autowired services
- Flexible support for common imgproxy processing options
Frequently asked questions about Imgproxy Bundle
- Is mezcalito/imgproxy-bundle a Laravel package?
- No. It is a Symfony bundle for Symfony 6.4/7.x with Twig and PHP 8.2+, and the catalog classification as a Laravel package is incorrect. It provides configuration for the imgproxy host plus key and salt, a URL-signing service, and a Twig extension. For Laravel, do not install it; use it as a reference specification and port the signing logic into a small service class or Blade directive.
- How do I install and configure mezcalito/imgproxy-bundle?
- Install it with Composer in a Symfony application, add the mezcalito_imgproxy configuration with your imgproxy host, hex key, and salt, then use the provided Twig filter to generate signed URLs. The bundle is only a thin binding layer; the real setup work is running imgproxy itself via Docker or imgproxy Cloud, wiring IMGPROXY_KEY and IMGPROXY_SALT, and placing a CDN in front. Do not treat installation as the hard part, because the infrastructure and secrets are where most effort goes.
- Can I use imgproxy with Laravel Blade instead of Twig?
- Yes, but not by installing this bundle. imgproxy signing is HMAC-SHA256 over the URL path, hex-encoded with the key and salt, which is roughly 40 to 80 lines of PHP. Implement that as a small Laravel service and expose it through a Blade directive or helper. Pulling Symfony framework contracts into a Laravel app for a string-signing utility is an anti-pattern and adds risk without benefit.
- How does imgproxy URL signing work and why is it required?
- imgproxy signs the processing path with HMAC-SHA256 using a hex key and salt, and the signature must be verified server-side. If signing is optional or the bundle generates unsigned URLs, your deployment becomes an open image-resizing proxy, which is a cost and abuse vector and potentially an SSRF surface if user-supplied source URLs are allowed. Always set IMGPROXY_KEY and IMGPROXY_SALT, reject unsigned requests, and configure IMGPROXY_ALLOWED_SOURCES.
- Which imgproxy options and presets does the bundle support?
- The bundle supports configurable presets and services for resizing, cropping, and format conversion, but it is a thin URL builder rather than an image engine. Before relying on it, confirm which options it actually models, including resize fit or fill, gravity, quality, automatic format negotiation, and DPR. Also ask whether there is an escape hatch for raw processing paths you need but the builder does not model.
- Does mezcalito/imgproxy-bundle support key rotation or expiring signed URLs?
- That is not documented in the provided material and should be resolved in a spike before production. Without key rotation, a leaked salt is a permanent incident, so plan for rotating key and salt pairs at the imgproxy or proxy layer even if the bundle does not support it. Expiring signed URLs likely require custom signing logic, so verify this explicitly if you need time-limited access.
- What are alternatives to imgproxy-bundle for Laravel image processing?
- For in-process manipulation, LiipImagine and Intervention Image are common choices, while imgproxy moves CPU-bound work out of PHP-FPM entirely. Laravel teams often use a small custom imgproxy signing service, Glide, or a hosted image CDN instead of a Symfony bundle. The key trade-off is whether you want derivatives stored locally or signed, cacheable URLs generated on demand.
- Is mezcalito/imgproxy-bundle actively maintained and safe to depend on?
- It has about 11 stars, zero dependents, and a single-agency maintainer, so community validation is low and the bus factor is one. The MIT license means you can fork it, and you should assume you may need to. Code risk is low because the surface area is small and there is a recent release, but ecosystem risk is medium and the opportunity risk is high for a niche utility.
- How should I test an imgproxy integration in a Laravel app?
- Start with unit tests that compare generated signatures against known HMAC-SHA256 vectors, then add feature tests asserting that your URL builder produces the expected paths and presets. Run an integration test against a local imgproxy container to confirm signed URLs work and unsigned requests are rejected. Also test source allowlisting and URLs containing query strings or already-encoded characters.
- What production concerns should I check before using imgproxy?
- Enforce signatures server-side, allowlist source hosts, keep key and salt in a secrets manager, and put a CDN in front for caching. Confirm how the bundle handles plain versus base64 source encoding and whether cache-busting is left entirely to the caller. Monitor for abuse and have a key-rotation plan ready, because a leaked salt without rotation is a permanent incident.
Weaver
How can I help you explore Laravel packages today?