Download the PHP
package imsus/laravel-imgproxy without Composer
On this page you can find all versions of the php package
imsus/laravel-imgproxy. It is possible to download/install
these versions without Composer. Possible dependencies are resolved
automatically.
After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.
Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories.
In this case some credentials are needed to access such packages.
Please use the auth.json textarea to insert credentials, if a package is coming from a private repository.
You can look here for more information.
Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
To use Composer is sometimes complicated. Especially for beginners.
Composer needs much resources. Sometimes they are not available on a simple webspace.
If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
imgproxy integration for Laravel. Generate signed, processed image URLs with an immutable fluent builder, render responsive `` and `` tags with LQIP placeholders, and build sources from any Storage disk — public disks get plain URLs, private disks get pre-signed temporary URLs.
## Requirements
- PHP ^8.4
- Laravel 13
- An imgproxy server (v4 recommended; the option segments target the v4 processing docs)
## Installation
You can install the package via Composer:
> **Using 1.x?** v1 stays available. Pin `^1.0` to keep the last 1.x release, or `1.x-dev` for the maintenance branch. v1 requires PHP ^8.2 and Laravel 10–12; v2 requires PHP ^8.4 and Laravel 13. The v1 source lives on the [`1.x` branch](https://github.com/imsus/laravel-imgproxy/tree/1.x), and its Packagist versions remain published. Migrating? See [UPGRADING](UPGRADING.md).
Publish the configuration file:
You may publish all of the package's resources at once:
The component templates publish to `resources/views/vendor/imgproxy` (the `laravel-imgproxy-views` tag) and override the package defaults.
## Configuration
The default instance reads its connection details from the environment, so the package works after setting three variables:
`IMGPROXY_KEY` and `IMGPROXY_SALT` are the hex-encoded values configured on the imgproxy server. When they are absent, URLs are generated unsigned with an `unsafe` signature slot — fine for local development, but configure them for anything exposed to the internet. Use `php artisan imgproxy:key` to generate a fresh pair.
The published `config/laravel-imgproxy.php` supports multiple named instances, each with its own server, credentials, signature size, and encoding:
Per-instance options:
- `url` — base URL of the imgproxy server, without a trailing slash.
- `key` / `salt` — hex-encoded HMAC credentials; `null` generates unsigned URLs.
- `signature_size` — signature bytes to keep (1–32), matching the server's `IMGPROXY_SIGNATURE_SIZE`; `null` keeps the full digest.
- `encoding` — source encoding: `base64` (URL-safe, no padding, the default) or `plain` (percent-encoded source behind a `plain/` prefix).
Named presets — reusable sets of processing options defined in config and shared across instances — are also supported. See the [documentation](#documentation) for details.
## Quick Start
The `Imgproxy` facade and the `imgproxy()` helper both resolve the default instance:
The builder exposes **two API layers**. The headline is the *intent* layer: high-level methods that express the desired outcome in domain terms (`cover`, `fit`, `orient`, `toWebp`, `storePublicly`, …) and compile down to imgproxy option segments. When an intent method isn't wired up — or you know exactly which wire option you want — drop down to the typed *processing-option* layer, where every imgproxy v4 option has one validating method (resize, crop, gravity, blur, watermark, format, and more). Enum arguments accept the enum or its string value interchangeably (`Gravity::Smart` and `'sm'` produce the same URL). For options not yet covered, `withOption()` appends a segment verbatim. `url()` and `__toString()` return the full URL; either works as a terminal call.
Both layers are immutable, so every mutation returns a new instance. A base builder can be reused for several variants without accidental mutation:
### Signing
With a key and salt configured, the `unsafe` slot is automatically replaced by an HMAC-SHA256 signature:
The signature covers the exact path emitted, so encoding choice and signing are computed together. `signature_size` truncates the signature to match the server; an empty key or salt disables signing.
### Storage Disks
Sources can come from any Laravel Storage disk. Public disks yield the disk's `url()`; private disks yield a pre-signed `temporaryUrl()`. The Storage macro is the most direct form:
At the facade entry, `fromStorage()` mirrors the macro (source-subject-first, path then disk) and hands you the same builder:
For an explicit source kind, `fromPath()` and `fromUrl()` build straight from a path or a URL. The builder also has an equivalent `->disk($disk, $path)` method, with an optional expiration in seconds or as an absolute `DateTimeInterface`:
See the [Storage Integration](/guide/storage-integration) documentation for the full macro and `->disk()` API.
### Materializing Processed Images
Instead of returning a URL, `toStorage()` fetches the processed image from imgproxy and writes it to any Storage disk, returning a `StoredImage` representation of the stored file. `storePublicly()` is the same with `['visibility' => 'public']` already applied:
The response body is streamed to the disk, so large images never load fully into memory. An existing file at the path is overwritten. When imgproxy responds with a non-2xx status or the disk write fails, an `ImgproxyStorageException` is thrown. On private destination disks, `url()` yields a pre-signed `temporaryUrl()` (5 minutes by default).
## Blade Components
The package ships two Blade components: `` for a single `` with responsive srcsets, and `` for format negotiation with a fallback image. Both support LQIP placeholders, width or DPR candidates, named presets, lazy loading by default, and Storage disk sources:
## Artisan Commands
### `imgproxy:key`
Generates a fresh 32-byte key and salt pair for URL signing, printed as environment lines ready for `.env`:
The command never writes to `.env` itself.
### `imgproxy:health`
Checks an instance's `/health` endpoint and exits non-zero when the instance is unreachable, unhealthy, or not configured:
## Documentation
The full documentation — every option method, the enums, presets, security, storage integration, and troubleshooting — is available at [https://imsus.github.io/laravel-imgproxy/](https://imsus.github.io/laravel-imgproxy/), with the source in [`docs/`](docs/).
## Testing Against a Real imgproxy
The test suite includes live checks against a real imgproxy running locally in Docker. They are gated behind three environment variables and skip when they are not set (CI never sets them):
The key and salt must match the local server's `IMGPROXY_KEY` / `IMGPROXY_SALT`. With the variables exported, the live tests run as part of `composer test`.
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Upgrading from 1.x? See [UPGRADING](UPGRADING.md).
## Contributing
Thank you for considering contributing to Laravel imgproxy! Please review our [contributing guide](.github/CONTRIBUTING.md) to get started, and our [code of conduct](CODE_OF_CONDUCT.md).
## Security Vulnerabilities
Please review [our security policy](.github/SECURITY.md) on how to report security vulnerabilities.
## Credits
- [Imam Susanto](https://github.com/imsus)
- [All Contributors](../../contributors)
## License
Laravel imgproxy is open-sourced software licensed under the [MIT license](LICENSE.md).
All versions of laravel-imgproxy with dependencies
Composer command for our command line client (download client)This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free.Standard composer command
The package imsus/laravel-imgproxy contains the following files
Loading the files please wait ...
Loading please wait ...
Before you can download the PHP files, the dependencies should be resolved. This can take some minutes. Please be patient.
