Documentation menu
On this page
Packages · v2.x
Image
The Image package (src/packages/Image) processes the images of the application with the GD extension of PHP, without any other dependency: thumbnails and resized copies generated on demand and cached, conversion to WebP or AVIF, photos turned upright from their EXIF orientation, metadata (GPS position, camera) removed.
Module
| Manager | NeoPHP\Package\Image\ImageManager (final) |
| Interface | NeoPHP\Package\Image\ImageManagerInterface |
| Attribute | #[Package(provider: ImageProvider::class, requires: [UploadManager::class])] |
| Requires | Upload component; PHP extension gd (with WebP support for WebP, imageavif() for AVIF); exif recommended |
Inject ImageManagerInterface in a service, a command or a controller:
use NeoPHP\Package\Image\ImageManagerInterface;
public function __construct(private ImageManagerInterface $images)
{
}
The module is enabled by default. To disable it in a project, add it to config/config.php (see the Kernel documentation):
NeoPHP\Package\Image\ImageManager::class => false,
The public API of the module is its manager and its interface, Model\Image, the exception and the classes documented below. The classes marked @internal are used by the framework only.
Quick start
Store a photo, then prepare it (upright, without metadata, at most 2560 pixels, WebP):
#[Route('/photos', name: 'photo_upload', methods: ['POST'])]
public function upload(Request $request): Response
{
$path = $this->storeUpload($request->files->get('photo'), 'photos'); // photos/3f9c…e1.jpg
$path = $this->optimizeImage($path, ['format' => 'webp']); // photos/3f9c…e1.webp
// ... save $path in the database
return $this->redirectToRoute('photo_list');
}
Display it with a preset of config/packages/image.yaml:
<img src="{{ image(photo.path, 'thumbnail') }}" width="300" height="300" alt="">
<a href="{{ image(photo.path, 'medium') }}">Open</a>
The derivative (public/media/cache/thumbnail/photos/3f9c…e1.webp) is generated the first time it is displayed, then served by the web server like any static file.
Configuration
neo install generates config/packages/image.yaml:
cache_path: '%kernel.public_path%/media/cache'
cache_url: /media/cache
quality: 82
max_pixels: 50000000
presets:
thumbnail: { width: 300, height: 300, mode: cover, format: webp }
medium: { width: 1200, height: 1200, mode: fit, format: webp }
optimize:
max_width: 2560
max_height: 2560
format: ~
quality: 85
| Key | Default | Description |
|---|---|---|
cache_path |
public/media/cache |
directory of the derivatives (must be under public/) |
cache_url |
/media/cache |
public URL of cache_path |
quality |
82 |
default quality of JPEG, WebP and AVIF (0 to 100) |
max_pixels |
50000000 |
images with more pixels (width × height) are refused before being decoded |
presets |
{ } |
named transformations, see Presets |
optimize |
see above | default options of optimize() |
/public/media/cache/ is added to the .gitignore of new projects.
Presets
| Option | Default | Description |
|---|---|---|
width, height |
~ |
size of the box in pixels; at least one of them |
mode |
fit |
fit: inside the box, ratio kept; cover: fills the box exactly and cuts what overflows (a single dimension gives a square); resize: exact size, the ratio can change (~ for a dimension keeps the ratio) |
position |
center |
part kept by cover: center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right |
format |
~ |
webp, jpeg, png, gif, avif, or ~ for the format of the source |
quality |
quality |
quality of this preset |
upscale |
false |
enlarges the images smaller than the box |
presets:
avatar: { width: 96, mode: cover, format: webp } # 96x96 square
banner: { width: 1600, height: 400, mode: cover, position: top }
gallery: { height: 400, mode: fit } # height 400, any width
print: { width: 3000, format: jpeg, quality: 95 }
A derivative is generated again when its source is more recent. After a change of a preset, run php bin/neo image:clear <preset>: the derivatives are generated again on their next display.
The photos are always turned upright (EXIF orientation) before the preset is applied, and the derivatives never contain metadata.
Displaying an image
The image() view function returns the URL of a derivative, generated when it is missing or outdated:
<img src="{{ image(user.avatar, 'avatar', asset('images/avatar.webp')) }}" alt="">
<img src="<?= $this->image($user->getAvatar(), 'avatar', '/images/avatar.webp') ?>" alt="">
image(path, preset, default = null) accepts a path relative to the upload directory (photos/a.jpg, as returned by storeUpload()) or a URL of the uploads (/uploads/photos/a.jpg). It returns default when the path is empty or the file does not exist, and the URL unchanged for an external URL (https://…). The URL contains the sub-directory of the application.
In a controller, imageUrl($path, $preset, $default = null) does the same (ImageController trait of AbstractController); in a service, $images->url($path, $preset, $default).
The first display of a page with many new images generates all of them: generate them in advance with image:warmup, or call thumbnail() in a job of the Queue package after the upload.
Optimizing an upload
Phone photos are large (4000 × 3000, 3 to 8 MB), often stored sideways with an EXIF orientation, and contain the GPS position where they were taken. optimize() replaces the file with a clean copy:
- turned upright according to its EXIF orientation;
- shrunk to
max_width×max_height(ratio kept, never enlarged); - converted to
formatwhen it is given (the extension changes:a.jpgbecomesa.webp, the old file is deleted); - saved without any metadata.
$path = $images->optimize('photos/a.jpg'); // same path
$path = $images->optimize('photos/a.jpg', ['format' => 'webp', 'max_width' => 1920]); // photos/a.webp
It returns the new path (relative when the given path was relative): save this one. The derivatives of the image are deleted. GIF images are left untouched unless a format is given (GD would keep only the first frame of an animated GIF).
Editing an image
open($path) and read($bytes) return a NeoPHP\Package\Image\Model\Image, whose methods change the image and return it:
$images->open('photos/a.jpg')
->autoOrient()
->cover(800, 800, 'top')
->greyscale()
->save($images->getCachePath() . '/custom/a.webp', 'webp', 80);
$bytes = $images->read($request->getContent())->fit(512, 512)->encode('png');
| Method | Description |
|---|---|
Image::fromFile(string $path, int $maxPixels = 0), Image::fromString(string $data, string $name = 'string', int $maxPixels = 0), Image::canvas(int $width, int $height, string $format = 'png') |
create an image |
getWidth(), getHeight(), getFormat(), getMimeType(), getOrientation(), getResource(): GdImage |
information |
autoOrient() |
turns the photo upright according to its EXIF orientation |
fit(?int $width, ?int $height, bool $upscale = false) |
inside the box, ratio kept |
cover(int $width, int $height, string $position = 'center', bool $upscale = false) |
fills the box and cuts what overflows |
resize(?int $width, ?int $height) |
exact size (null keeps the ratio) |
crop(int $x, int $y, int $width, int $height) |
cuts a rectangle |
rotate(float $degrees, string $background = 'transparent') |
clockwise rotation (#RRGGBB or #RRGGBBAA for the corners) |
flip(bool $horizontal = true, bool $vertical = false), greyscale() |
mirror, shades of grey |
encode(?string $format = null, int $quality = 82): string |
the bytes of the image (format of the source by default) |
save(string $path, ?string $format = null, int $quality = 82): string |
writes the file (format from the extension by default), through a temporary file |
Image::supports(string $format): bool |
whether GD can write this format on this server |
The transparency is kept in PNG, WebP, AVIF and GIF; a transparent image saved as JPEG gets a white background. clone $image gives an independent copy.
Commands
php bin/neo image:warmup
php bin/neo image:warmup thumbnail medium --directory=photos
php bin/neo image:clear
php bin/neo image:clear thumbnail
| Command | Description |
|---|---|
image:warmup [presets...] [--directory=] |
generates the derivatives of the images of the uploads (all presets by default) |
image:clear [preset] |
deletes the derivatives (of one preset) |
ImageManagerInterface
| Method | Description |
|---|---|
open(string $path): Image |
loads an image (absolute path, path relative to the uploads or URL of the uploads) |
read(string $data): Image |
loads an image from its bytes |
thumbnail(string $path, string $preset): string |
absolute path of the derivative, generated when needed |
url(?string $path, string $preset, ?string $default = null): ?string |
public URL of the derivative |
optimize(string $path, array $options = []): string |
prepares an original, returns its new path |
forget(string $path): int |
deletes the derivatives of an image |
clear(?string $preset = null): int |
deletes the derivatives |
getPresets(): array, getCachePath(): string |
configuration |
The manager is also available with the image container id. Call forget($path) when an image is replaced or deleted (deleteUpload() does not know the derivatives).
Security and limits
- A relative path is resolved in the upload directory:
..is refused, so a path coming from the database cannot reach another file. max_pixelsrefuses an image before decoding it: a small file can declare a huge size and fill the memory (decompression bomb). GD needs about 4 bytes per pixel: a 12 megapixel photo uses about 50 MB of memory while it is processed; raisememory_limitif needed.- The type of a file is detected from its content, never from its extension.
- Derivatives are public files: never use a preset on a private image, serve it with a file response of the Http component after checking the access instead (
open()thensave()invar/). - AVIF needs a GD built with AVIF support (
Image::supports('avif')); animated GIF and WebP images lose their animation.
Errors
Every error throws NeoPHP\Package\Image\Exception\ImageException (extends FrameworkException): GD missing, unknown preset or invalid option, file missing or not a supported image, image larger than max_pixels, path outside the uploads, format not supported by GD, file that cannot be written.
Changelog
- v2.8.0 —
Helper/Doctor/ImageCheck:neo doctorchecks GD, the formats of the presets and the cache directory (see the Doctor documentation). - v2.6.0 — Image package:
ImageManagerandImageManagerInterface,Model\Image(fit, cover, resize, crop, rotate, flip, greyscale, EXIF orientation, encoding in JPEG, PNG, GIF, WebP and AVIF without metadata), presets with cached derivatives,image()view function,imageUrl()/optimizeImage()controller helpers,optimize()for the uploads,max_pixelsprotection,image:warmupandimage:clearcommands,config/packages/image.yamlgenerated byneo install.