Download the PHP package isapp/laravel-imagetools without Composer

On this page you can find all versions of the php package isapp/laravel-imagetools. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

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.
Please rate this library. Is it a good library?

Informations about the package laravel-imagetools

Laravel Image Tools

Deterministic, query‑driven image generation for Laravel — inspired by vite-imagetools.

Laravel Image Tools by ISAPP

Packagist Tests PHP


Features

Requirements

Installation

Auto‑discovery will register the service provider and the ImageTools facade.

Publish config (optional)

If you want to customize defaults, publish the config file:

Quick start

When the source is narrower than 640px, asset() returns null and src is empty. See Larger than the source.

Pure PHP

Source on another disk — read the original from any Laravel disk (e.g. S3), mirroring Storage::disk() (see Reading the source from a disk):

Also supported (and detected by the scanner):

Configuration

All options live in config/image-tools.php (with inline comments). You can also control them via ENV:

Key options:

The request is canonicalized: query keys are sorted before hashing, so ?h=630&w=1200 equals ?w=1200&h=630.

Zero‑downtime deploys (Forge, Envoyer, Deployer, Vapor): the manifest is written at runtime when asset() generates an image on demand. bootstrap/cache is per‑release, so those entries are lost on the next deploy (the next miss adopts the file that is still on the disk, without an encode). If you rely on on‑demand generation, point the manifest at the shared storage directory, e.g. IMAGE_TOOLS_MANIFEST_PATH=storage/app/image-tools.php. If you only pre‑generate at build time with imagetools:generate, the default is fine.

Query options

Key Type Description
w int Target width (px). Without fit and greater than the source width, no file is stored — see Larger than the source.
h int Target height (px). Without w or fit and greater than the source height, no file is stored.
fit enum Geometry mode from Spatie\Image\Enums\Fit (e.g. Contain, Fill, Max, …). Requires w and h.
q int Output quality (1..100).
format enum Output format: jpeg, png, gif, webp, avif.
lossless bool Lossless WebP: 1, true, on or yes switch it on. Takes effect when the output is a WebP and the driver is Imagick; otherwise the ordinary encode runs. A switch that is on is part of the canonical name, so the lossless variant is its own file; a switch that is off resolves to the same file as the plain call.
optimize bool On by default. 0, false, off or no skip the optimizer chain, so the file is the encoder's output at q. A switch that is off is part of the canonical name (its own file); a switch that is on resolves to the same file as the plain call.

queue is a control flag, not a transform — see below. It is excluded from the canonical name, so ?w=800 and ?w=800&queue=1 resolve to the same file.

Optimizers

After each encode, an optimizer chain rewrites the file. By default it is the spatie/image-optimizer chain. That chain encodes a WebP again with cwebp -q 90 and an AVIF with cq-level=23, whatever q the query asks for. A lossy WebP or AVIF can then grow larger than the encoder's output.

A lossless WebP (lossless=1) always uses its own lossless cwebp chain. driver and optimizers are not part of the file name. After you change one of them, run php artisan imagetools:regenerate --all to encode the existing entries again.

Larger than the source

A resize by w or h does not enlarge a source that is smaller than the request. An enlarged file holds no more detail than the source, and it is much heavier. For example, ?w=3840 on a 1280px source stores no file. The manifest records the request with 'path' => null, and asset() returns null. Later calls read that entry and do not load the source again.

{{ null }} prints nothing, but the text around it still prints. A srcset needs a check before each candidate:

The src request has no w, so it is never larger than the source, and asset() never returns null for it. The package does not add a candidate at the source width: for a 1280px source, the list above keeps only 768w. Add widths that match your sources if you need more.

Upgrading from 1.3 or earlier: existing entries keep their enlarged files, because the key and the filename do not change. Two commands apply the rule:

The enlarged file is deleted even when the manifest no longer holds its entry, for example a per‑release bootstrap/cache. Pages cached before the run (full‑page cache, CDN HTML) still point to the deleted files, so clear those caches after it. When opcache does not check timestamps (opcache.validate_timestamps=0), reload PHP‑FPM too: the web processes keep their compiled copy of the manifest. Restart long‑lived processes as well (php artisan queue:restart, php artisan octane:reload): they keep the manifest in memory and would print URLs to the deleted files. When several hosts keep their own manifest but share one output disk, run the command on each host: the files it deletes are the ones the other manifests still point to. A later change to allow_upscale needs the same steps.

A null entry stays null when you replace its source with a larger image: the key does not change, so nothing reads the source again. Run imagetools:regenerate --all after you replace a source.

Deferred (queued) generation

On a page with many new images — especially a responsive srcset with several widths — generating them all in the first request is slow, and the request can time out. Queued mode moves the encode to a worker, so the page responds at once.

Turn it on for every call in the config:

A queue flag in the query overrides the config for one call, in both directions:

When the image has not been generated yet:

The job is unique per derivative (ShouldBeUnique, keyed on the canonical seed). While it is pending, later renders queue nothing and get the fallback again. This requires a cache store that supports atomic locks (file, redis, database, memcached, …).

Things to know:

Configuration (all optional — see config/image-tools.php):

Pre-generating with php artisan imagetools:generate ignores the queue flag and produces the same files, so you can warm everything at build time instead.

Reading the source from a disk (e.g. S3)

By default the source image is read locally, relative to base_path(). To read the original from a configured Laravel filesystem disk instead — for example an S3 bucket — scope the call with disk(), mirroring Storage::disk():

The scanner command (imagetools:generate) finds the disk('…') form when the disk name is a literal string: ImageTools::disk('s3')->asset('…') and app('image-tools')->disk('s3')->asset('…'). It does not find a disk from a variable (disk($name)) or a path built at runtime. Those images are generated on demand, or in the queue.

spatie/laravel-medialibrary

ImageTools::media() makes a derivative of the original file of a medialibrary Media:

Commands

Pre‑generate from code (CI‑friendly)

Scans your codebase and generates images for discovered usages.

The scanner looks into config('image-tools.blade_paths') and config('image-tools.php_paths') and detects:

Clear generated files

Removes the manifest file, then deletes every file it referenced. The manifest is read and removed under its write lock; the .lock file stays in place. Each file is then deleted under the same lock, after the command reads the manifest again: a request that missed in the meantime and adopted a file keeps it.

Regenerate broken files

Walks the manifest and rebuilds every entry whose stored file is missing or empty — the shape a killed optimizer leaves behind. Each entry is rebuilt from the source recorded next to it, so the key and the filename stay the same.

Option Effect
--all Regenerate every entry, not only the broken ones.
--dry-run Report what would be regenerated and write nothing.

The manifest is rewritten entry by entry and is never deleted, so the site keeps serving while the command runs. The exception is an entry that becomes larger than the source: its enlarged file is deleted, and pages cached before the run still point to it. An entry that cannot be rebuilt keeps its current value and is reported: the command exits with a non‑zero status when anything failed. Entries written before the source was recorded are skipped — run imagetools:generate to rebuild those from the code.

An entry with 'path' => null is a request larger than the source. It has no file by design, so it counts as healthy. --all rebuilds it by the current allow_upscale value.

A rebuild that finds the request larger than the source prints No file [<key>]: the request is larger than the source. The summary counts it as larger than the source, not as regenerated. The exit status stays zero. A --dry-run rebuilds nothing, so it cannot find these entries.

Each write takes a lock on the manifest and starts from the file as it is on disk, so an entry that a web request or a queue worker adds while the command runs is kept. A long‑lived process no longer writes its old copy of the manifest back over the command's changes. When the lock cannot be taken, the write goes ahead without it and a warning is logged.

Prune orphan files

Deletes orphans: generated files on the output disk that no entry of the manifest references. Orphans stay behind, for example, after a manifest was lost or replaced: the new manifest knows only the files that requests asked for since then.

A changed query is not an orphan case. The entry of the old query stays in the manifest and still references its file, so prune keeps that file.

Option Effect
--dry-run List the orphans and delete nothing. More than half of orphans gives a warning, not a refusal.
--force Run also with a manifest under bootstrap/cache, or when more than half of the files are orphans.

The command refuses to run, and deletes nothing, in these cases:

Before you run it:

  • Pages cached before the run (a full‑page cache, CDN HTML) can still point to the deleted files. Clear those caches after it.
  • The command reads only the default manifest. Do not run it when several hosts with their own manifest, or extra manifests loaded with loadManifest($path), share one output disk: their files count as orphans.

What gets written

When the manifest has no entry for a request but the file at its name is on the disk (for example, a lost manifest), the file is adopted: the entry is written again and nothing is encoded. The source is still loaded, because the size check needs it. A disk that cannot answer the check (for example S3 credentials without the right to list, which turn a missing key into a 403) logs a warning, and the image is encoded.

The check of the stored file runs while the manifest lock is held, so a slow disk holds up other writers. Give an S3 or R2 disk an HTTP timeout, for example 'http' => ['connect_timeout' => 5, 'timeout' => 30] in config/filesystems.php.

Tips

Troubleshooting

Testing

The tests draw their image fixtures with GD, so development needs ext-gd.

The suite includes an S3 integration test (PHPUnit group s3) that runs against a real S3‑compatible endpoint to verify uploads, URL generation and the clear command. It is skipped unless AWS_ENDPOINT + AWS_BUCKET are set, so the default run needs no infrastructure. To run it locally against MinIO:

CI runs this automatically in a dedicated MinIO job.

Versioning

This package follows Semantic Versioning. See CHANGELOG.md for release notes.

Security

If you discover a security issue, please email [email protected] instead of opening a public issue.

Contributing

Contributions are welcome! If you have suggestions for improvements, new features, or find any issues, feel free to submit a pull request or open an issue in this repository.

Thank you for helping make this package better for the community!

License

This project is open-sourced software licensed under the MIT License.

You are free to use, modify, and distribute it in your projects, as long as you comply with the terms of the license.

Credits

Built by ISAPP. Uses the excellent spatie/image.


Check out our software development services at isapp.be.


All versions of laravel-imagetools with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
illuminate/bus Version ^10.0|^11.0|^12.0|^13.0
illuminate/contracts Version ^10.0|^11.0|^12.0|^13.0
illuminate/support Version ^10.0|^11.0|^12.0|^13.0
illuminate/filesystem Version ^10.0|^11.0|^12.0|^13.0
illuminate/view Version ^10.0|^11.0|^12.0|^13.0
nikic/php-parser Version ^5
spatie/image Version ^3.9.6
spatie/image-optimizer Version ^1.10
symfony/finder Version ^6.4|^7.0|^8.0
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 isapp/laravel-imagetools contains the following files

Loading the files please wait ...