Download the PHP package onlinedigital/laravel-perfect-image without Composer
On this page you can find all versions of the php package onlinedigital/laravel-perfect-image. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download onlinedigital/laravel-perfect-image
More information about onlinedigital/laravel-perfect-image
Files in onlinedigital/laravel-perfect-image
Package laravel-perfect-image
Short Description Automatic responsive image optimization for Laravel
License MIT
Informations about the package laravel-perfect-image
Laravel Perfect Image
Automatic responsive image optimization for Laravel. Detects rendered image dimensions, caches the most common resolutions, and generates srcset attributes automatically.
Features
- Automatic detection of rendered image dimensions via JavaScript
- Caches the most common resolutions per image
- Driver-based URL generation (supports multiple image services)
- Blade directive for easy usage
- Lazy resize tracking
Installation
Add Middleware (Optional - for automatic JS injection)
Add to your bootstrap/app.php:
Or apply to specific routes:
Publish Config
Config Options
Usage
Basic Usage
In your Blade templates:
Example:
This generates:
sizes is learned from how the rendered width changes with the viewport width
(100vw until something has been learned).
Custom Sizes
The third argument is a list of widths that overrides the learned resolutions:
The directive accepts the same arguments:
JavaScript
While collect_dimensions is enabled, the JavaScript is injected automatically
(before </body>) on pages that contain tracked images. It does not need jQuery.
Creating Custom Drivers
Create a class that implements OnlineDigital\PerfectImage\Contracts\Driver:
Register it in a service provider:
How It Works
- First Visit: If collection is enabled and no resolutions are cached for an image, the Blade directive adds
src, data attributes and an onload handler - JavaScript Tracking: On page load and whenever an image or the window is resized (throttled, with a trailing call), JS measures every tracked image
- Dimension Collection: Once enough samples were gathered, all images are sent in a single batch to the
_perfect_image_observerendpoint - Caching: The server saves the most common resolutions (at most
max_resolutions) and asizesvalue - Applying: The response contains
src,srcsetandsizes, which JS applies without reloading the page - Subsequent Visits: srcset is generated from cached resolutions
Collecting all resolutions automatically (Playwright)
Instead of waiting for someone to resize a browser window, a script can open the pages, sweep the viewport from the smallest phone (320px) to a 2K desktop (2560px) and trigger the collection. This is also the workflow meant for coding agents: after adding a page or a component, run the collector for those URLs and commit the result.
Setup (once)
Set the JSON file store (PERFECT_IMAGE_CACHE_DRIVER=storage_file). Collected data is written to
resources/perfect-image.json, so it can be committed and deployed with the code.
Run
The application must be running (for example php artisan serve) on the same machine/filesystem.
What the command does:
- Turns the collection on with a temporary flag file (
storage/app/perfect_image_collect.flag). The flag is ignored in production, so there is no per request cost there. It is removed afterwards, and the previous state is restored even if the command is interrupted. - Runs
scripts/collect.mjswith Playwright. For every page it loads the page, forces lazy images to load, resizes the viewport step by step (and exactly at the usual breakpoints) and measures every tracked image. - Calls the collect API once per page and prints a JSON report (
--jsonfor JSON only).
Useful options:
| Option | Default | |
|---|---|---|
--base-url |
app.url |
Running application |
--max-per-template |
3 | Discovered pages visited per route (/product/{slug}) or URL directory |
--all |
Visit every discovered URL | |
--min-width, --max-width, --step |
320, 2560, 40 | Viewport sweep |
--concurrency |
2 | Pages in parallel (1 with --fresh) |
--header="Name: value" |
Extra request headers | |
--storage-state=file.json |
Playwright storage state for pages behind a login |
Notes:
- Only images rendered with
@perfect_image_srcset/perfect_image_srcset()are measured. - Images inside carousels, tabs, modals or hover menus have no size until they are visible. Visit the
page state in a custom Playwright script, or measure them with real users (
collect_dimensions). --from-routesvisits static GET routes. Do not use it if one of them has side effects.- Models are resolved for routes with exactly one parameter that is type-hinted with an Eloquent model.
Without artisan
The script can be used directly (collection must already be enabled, see collect_dimensions):
Exit codes: 0 ok, 1 errors, 2 nothing measured or images left unmeasured, 3 collection disabled.
Coding agents
See AGENTS.md for the short workflow to give to an agent.
Route
The package automatically registers the observer route:
Request body (resolutions items are [width, height] or [width, height, viewportWidth]):
Several images can be sent at once (this is what the JavaScript does):
Responses: 200 with the resulting src/srcset/sizes per image id, 422 for an invalid
payload, 403 (collect_dimensions_disabled) when collect_dimensions is off.
License
MIT