Laravel Imgproxy Laravel Package

Product Decisions This Supports

• Roadmap: image delivery and media pipeline features. v3.0.0 adds image-info URLs for imgproxy Pro, enabling product features that depend on image metadata (dimensions, format, orientation, etc.) without building a separate inspection service. This is relevant for media libraries, CMS previews, asset validation, and upload workflows.
• Build vs. buy. The package continues to wrap a mature imgproxy SDK rather than reimplementing URL signing, encryption, and transformation logic. The Pro-only infoBuilder() and imgproxyInfo() disk macro make the buy decision more nuanced: teams already paying for imgproxy Pro get more value, while teams on open-source imgproxy should treat these as unavailable.
• Configuration and platform flexibility. New config for argument separators, source chunk size/filename, trusted signatures, presets-only mode, and option aliases gives PMs levers for security posture, URL compatibility, and controlled feature rollout without forking the package.
• Upgrade and migration planning. The release is explicitly breaking: it requires hosmelq/imgproxy ^2.0, changes format() behavior, throws on previously tolerated invalid inputs, and requires rebuilding URLs for encrypted sources. This creates a scoped migration workstream that should be scheduled and tested rather than absorbed silently.
• Security and correctness improvements. Stricter validation for source encoding, custom IVs, and encryption keys turns silent misconfiguration into explicit failures, which is good for production reliability but may surface latent issues in existing configurations.

When to Consider This Package

Adopt or upgrade when:

• You use Laravel Storage disks with imgproxy and want a maintained integration rather than hand-rolled URL signing and macros.
• You need image-info URLs and already have imgproxy Pro entitlements.
• You want centralized configuration for signatures, presets, separators, and encryption behavior.
• You can absorb a breaking upgrade: audit format() usage, replace it with build(extension: 'webp'), verify Storage macro calls pass extension/encoding correctly, and regenerate any encrypted URLs.
• You have test coverage for generated URLs and can validate that the hosmelq/imgproxy 2.0 upgrade does not change expected outputs in your environment.

Look elsewhere or defer when:

• You rely on encrypted sources at scale and cannot coordinate a URL rebuild across caches, CDNs, stored content, or external consumers.
• You are on imgproxy open source and the headline feature (image-info URLs) is unavailable; the upgrade cost may not be justified by the remaining changes alone.
• You have heavy custom URL-building logic tightly coupled to the old format() extension behavior or the previous SDK version.
• You need a stable, non-breaking dependency during a critical release window; pin to the prior major until migration work is resourced.

How to Pitch It (Stakeholders)

For executives: v3.0.0 is a capability and hardening release for our Laravel image pipeline. It unlocks image metadata features for teams with imgproxy Pro, adds configurable security and compatibility controls, and tightens validation so misconfigurations fail loudly instead of silently. The trade-off is a planned breaking upgrade: we need engineering time to update SDK dependencies, adjust format() usage, and rebuild encrypted image URLs. This is a scoped migration, not a drop-in patch.

For engineering: Treat this as a major-version migration. Upgrade hosmelq/imgproxy to ^2.0, audit all format() calls and replace with build(extension: 'webp'), confirm Storage macros pass extension/encoding, validate config for separators, presets-only mode, trusted signatures, and aliases, and add tests for invalid encoding/IV/key cases now throwing. Regenerate encrypted source URLs once and invalidate caches/CDN entries. Sequence the work behind a feature flag or staging validation if encrypted assets are customer-facing.