- How do I install imsus/laravel-imgproxy?
- Install it with Composer using composer require imsus/laravel-imgproxy. The package is a thin wrapper around an imgproxy server, so you still need a running imgproxy instance plus its key and salt configured in your environment. Adoption inside an existing ^2.x constraint requires only a normal composer update, with no config publish or migration step required.
- Which Laravel and PHP versions does this package support?
- The package is designed to be consumed inside the existing ^2.x constraint without breaking changes, so upgrades are additive within that line. Because it only emits imgproxy URL segments, it has no coupling to a new service or config surface. Check the package composer.json for the exact PHP and Laravel version constraints before installing.
- How do I generate a signed imgproxy URL for a file on a Storage disk?
- Use Imgproxy::fromStorage($path, $disk, $instance) and the package resolves the correct base URL for you. Public disks are resolved through url(), while private disks go through temporaryUrl(), mirroring the existing Storage macro behavior. There are also fromPath() and fromUrl() entry points if you already have a filesystem path or an absolute URL.
- What is the difference between resize(), cover(), and fit()?
- resize() is the original lower-level option and now sits alongside the newer intent methods cover() and fit(). cover() fills the target dimensions and crops the overflow, while fit() scales the image to fit inside the dimensions without cropping. resize() is marked deprecated in docblocks only, so it still runs identically but gives you no runtime or static-analysis warning, which makes it a governance and consistency question for your team rather than an immediate breaking change.
- How do I convert images to WebP, AVIF, JPEG, or PNG?
- Call toWebp(), toAvif(), toJpg(), or toPng() on the builder to compile the corresponding format segment into the URL. These are ergonomic compilers down to the same processing-option segments the typed option layer already emits, so the wire format is unchanged. Pair them with an explicit quality option if you need a specific compression level rather than the defaults.
- What does optimize() actually do by default?
- optimize() is a compound convenience call that defaults to WebP output at quality 70, so a single call changes both format and quality. If you expected it to just tune the JPEG you already have, you will get WebP instead, which is a content negotiation and cache-key concern, not only an aesthetic one. For predictable output, prefer explicit toWebp()/toJpg() plus your own quality option.
- How do I pass raw imgproxy options the intent API does not cover?
- Use withOption() as the wire-level escape hatch on the immutable builder. The layered design is intentional: intent methods for everyday product code, withOption() for anything the typed layer does not express. Advanced usage in the docs shows how to compose options such as contain to cover the documented non-goals.
- Why is my image not being resized when I use when() or unless()?
- The builder is immutable and Conditionable, so when() and unless() fall back to the original instance if your callback returns nothing. Arrow functions like fn ($b) => $b->cover(...) work because they return the new instance, but a statement-style closure that forgets to return silently discards the change, including the higher-order proxy form. Always return the new builder instance from conditional callbacks.
- Do imgproxy URLs generated from private disks expire?
- Yes. For private disks, fromStorage() resolves a temporaryUrl(), which embeds the storage expiry into the generated URL. If you cache rendered HTML or image URLs downstream, those cached URLs will eventually stop working, and the problem grows with adoption of fromStorage(). Treat URL caching as a design decision and regenerate signed URLs when needed.
- Is storePublicly() or fromStorage() a security risk for private assets?
- fromStorage() classifies a disk as public or private, and a misclassification turns a private asset into a durable, guessable, non-expiring URL, which is a security-relevant branch inherited from the Storage macro. storePublicly() writes files with public visibility and should be gated by a data-classification conversation rather than treated as a convenience flag. Review both calls against your asset sensitivity before rolling them out broadly.