Gestire il formato WebP in PHP
In PHP la gestione di WebP è alla portata di qualsiasi installazione con GD, a patto di conoscerne le peculiarità: la conversione obbligatoria delle immagini a tavolozza, la gestione esplicita dell'alfa con la sua scala invertita, l'orientamento EXIF da applicare a mano, l'assenza di supporto alle animazioni.
Per un'applicazione PHP che pubblica contenuti, WebP è da anni la scelta più sensata per le immagini: tutti i browser moderni lo supportano, la compressione con perdita produce file più leggeri di JPEG a parità di qualità, quella senza perdita batte spesso PNG, e il formato gestisce trasparenza e animazioni. PHP offre due strade per lavorarci: l'estensione GD, presente praticamente ovunque, e Imagick, il binding di ImageMagick, più potente ma non sempre installato sugli hosting condivisi.
In questo articolo partiremo dalla struttura binaria del formato, con un parser dell'intestazione in PHP puro, poi useremo GD per conversioni, ridimensionamenti, gestione della trasparenza e dell'orientamento EXIF. Vedremo quando conviene passare a Imagick, in particolare per le animazioni, e chiuderemo con un front controller che serve WebP solo ai client che lo accettano e con uno script CLI per convertire un archivio esistente. Il codice richiede PHP 8.1 o successivo.
Il formato in breve
Un file WebP è un contenitore RIFF: i primi quattro byte sono la stringa RIFF, i successivi quattro la dimensione del resto del file in little-endian, poi la stringa WEBP. Da lì in avanti si susseguono i chunk, ciascuno con un identificatore di quattro caratteri, una dimensione a 32 bit e il contenuto. Il primo chunk definisce la variante:
VP8(con lo spazio): compressione con perdita, basata su un fotogramma chiave del codec VP8, senza alfa. Larghezza e altezza occupano 14 bit ciascuna, dopo il codice di sincronizzazione9d 01 2a.VP8L: compressione senza perdita, con alfa nativo. Dopo il byte0x2fci sono 28 bit con larghezza e altezza meno uno e un bit che segnala l'uso dell'alfa.VP8X: formato esteso, usato per l'alfa con perdita, i profili ICC, i metadati EXIF e XMP e le animazioni. Contiene un byte di flag e le dimensioni della tela su 24 bit, meno uno.
Un parser dell'intestazione in PHP puro
La funzione getimagesize() riconosce WebP fin da PHP 7.1 e restituisce dimensioni e tipo MIME, ma non dice nulla su alfa, animazione e metadati. Un piccolo parser basato su unpack() colma la lacuna leggendo solo i primi 30 byte, ed è utile anche per rifiutare in anticipo i file sospetti.
<?php
// src/WebpInfo.php
declare(strict_types=1);
namespace App\Image;
final class WebpInfo
{
private const FLAG_ICC = 0x20;
private const FLAG_ALPHA = 0x10;
private const FLAG_EXIF = 0x08;
private const FLAG_XMP = 0x04;
private const FLAG_ANIMATION = 0x02;
private function __construct(
public readonly string $format,
public readonly int $width,
public readonly int $height,
public readonly bool $alpha = false,
public readonly bool $animated = false,
public readonly bool $icc = false,
public readonly bool $exif = false,
public readonly bool $xmp = false,
) {
}
public static function fromFile(string $path): ?self
{
$handle = @fopen($path, 'rb');
if ($handle === false) {
return null;
}
// Bastano i primi byte, qualunque sia la dimensione del file
$header = (string) fread($handle, 64);
fclose($handle);
return self::fromBytes($header);
}
public static function fromBytes(string $data): ?self
{
if (strlen($data) < 30 || !str_starts_with($data, 'RIFF') || substr($data, 8, 4) !== 'WEBP') {
return null;
}
return match (substr($data, 12, 4)) {
'VP8 ' => self::parseLossy($data),
'VP8L' => self::parseLossless($data),
'VP8X' => self::parseExtended($data),
default => null,
};
}
private static function parseLossy(string $data): ?self
{
// Codice di sincronizzazione del fotogramma chiave VP8
if (substr($data, 23, 3) !== "\x9d\x01\x2a") {
return null;
}
['width' => $width, 'height' => $height] = unpack('vwidth/vheight', $data, 26);
return new self('lossy', $width & 0x3FFF, $height & 0x3FFF);
}
private static function parseLossless(string $data): ?self
{
if (ord($data[20]) !== 0x2F) {
return null;
}
$bits = unpack('V', $data, 21)[1];
return new self(
'lossless',
($bits & 0x3FFF) + 1,
(($bits >> 14) & 0x3FFF) + 1,
alpha: (($bits >> 28) & 0x1) === 1,
);
}
private static function parseExtended(string $data): self
{
$flags = ord($data[20]);
// Gli interi a 24 bit si leggono aggiungendo un byte nullo e usando V
$width = unpack('V', substr($data, 24, 3) . "\0")[1] + 1;
$height = unpack('V', substr($data, 27, 3) . "\0")[1] + 1;
return new self(
'extended',
$width,
$height,
alpha: ($flags & self::FLAG_ALPHA) !== 0,
animated: ($flags & self::FLAG_ANIMATION) !== 0,
icc: ($flags & self::FLAG_ICC) !== 0,
exif: ($flags & self::FLAG_EXIF) !== 0,
xmp: ($flags & self::FLAG_XMP) !== 0,
);
}
}
Il formato v di unpack() legge un intero a 16 bit little-endian senza segno, V uno a 32 bit. Il terzo argomento, l'offset, è disponibile da PHP 7.1 ed evita di dover ritagliare la stringa con substr(). Su PHP a 64 bit il valore restituito da V è sempre positivo, quindi gli spostamenti di bit funzionano senza sorprese.
Verificare il supporto di GD
GD supporta WebP solo se è stato compilato con libwebp. Sulle distribuzioni Linux e nelle immagini Docker ufficiali di PHP, con l'estensione GD configurata tramite docker-php-ext-configure gd --with-webp, è normalmente così; conviene comunque verificarlo esplicitamente, magari in un controllo di salute dell'applicazione.
<?php
// check.php
$gd = function_exists('gd_info') ? gd_info() : [];
printf("GD: %s\n", $gd['GD Version'] ?? 'non disponibile');
printf("WebP in GD: %s\n", !empty($gd['WebP Support']) ? 'sì' : 'no');
printf("Lossless GD: %s\n", defined('IMG_WEBP_LOSSLESS') ? 'sì' : 'no');
printf("Imagick: %s\n", extension_loaded('imagick') && \Imagick::queryFormats('WEBP') ? 'sì' : 'no');
La costante IMG_WEBP_LOSSLESS, introdotta in PHP 8.1, abilita la compressione senza perdita in GD. Nel Dockerfile, per un'immagine basata su Debian, la configurazione tipica è questa:
FROM php:8.3-fpm
RUN apt-get update \
&& apt-get install -y --no-install-recommends libwebp-dev libjpeg62-turbo-dev libpng-dev \
&& docker-php-ext-configure gd --with-webp --with-jpeg \
&& docker-php-ext-install -j"$(nproc)" gd exif \
&& rm -rf /var/lib/apt/lists/*
L'estensione exif, installata insieme a GD, ci servirà per leggere l'orientamento delle fotografie. Un'ultima nota sulla sicurezza: nel settembre 2023 la vulnerabilità CVE-2023-4863 di libwebp, un heap overflow nella decodifica senza perdita sfruttato attivamente, ha riguardato anche GD e ImageMagick. Le immagini Docker di PHP vanno quindi ricostruite periodicamente, non solo quando cambia il codice.
Caricare un'immagine nel modo giusto
Prima di convertire bisogna caricare la sorgente in una risorsa GD, e qui si concentrano gli errori più comuni. Le fotografie degli smartphone sono spesso salvate ruotate, con la rotazione corretta annotata nel tag EXIF Orientation, che GD ignora. Le PNG a tavolozza, poi, non possono essere codificate in WebP così come sono: imagewebp() rifiuta le immagini a colori indicizzati. Infine, se la sorgente ha trasparenza, GD va istruito a conservarla.
<?php
// src/ImageLoader.php
declare(strict_types=1);
namespace App\Image;
use GdImage;
use RuntimeException;
final class ImageLoader
{
public static function load(string $path): GdImage
{
$info = @getimagesize($path);
if ($info === false) {
throw new RuntimeException("Formato non riconosciuto: {$path}");
}
$image = match ($info[2]) {
IMAGETYPE_JPEG => @imagecreatefromjpeg($path),
IMAGETYPE_PNG => @imagecreatefrompng($path),
IMAGETYPE_WEBP => @imagecreatefromwebp($path),
IMAGETYPE_GIF => @imagecreatefromgif($path),
default => false,
};
if ($image === false) {
throw new RuntimeException("Impossibile decodificare: {$path}");
}
// WebP richiede un'immagine truecolor
if (!imageistruecolor($image)) {
imagepalettetotruecolor($image);
}
// Conserva il canale alfa invece di fonderlo con lo sfondo
imagealphablending($image, false);
imagesavealpha($image, true);
if ($info[2] === IMAGETYPE_JPEG) {
$image = self::applyOrientation($image, $path);
}
return $image;
}
public static function applyOrientation(GdImage $image, string $path): GdImage
{
if (!function_exists('exif_read_data')) {
return $image;
}
$exif = @exif_read_data($path);
$orientation = (int) ($exif['Orientation'] ?? 1);
// imagerotate ruota in senso antiorario, quindi -90 equivale a 90 gradi orari
return match ($orientation) {
2 => self::flip($image, IMG_FLIP_HORIZONTAL),
3 => imagerotate($image, 180, 0),
4 => self::flip($image, IMG_FLIP_VERTICAL),
5 => imagerotate(self::flip($image, IMG_FLIP_HORIZONTAL), 90, 0),
6 => imagerotate($image, -90, 0),
7 => imagerotate(self::flip($image, IMG_FLIP_HORIZONTAL), -90, 0),
8 => imagerotate($image, 90, 0),
default => $image,
};
}
private static function flip(GdImage $image, int $mode): GdImage
{
imageflip($image, $mode);
return $image;
}
}
Il tipo dell'immagine viene determinato da getimagesize(), che legge i byte iniziali del file: l'estensione non conta, ed è giusto così, perché l'estensione di un file caricato da un utente non dimostra nulla. Le otto combinazioni di Orientation coprono rotazioni e specchiature; nella pratica le fotocamere usano quasi solo i valori 1, 3, 6 e 8.
Convertire in WebP con GD
La conversione vera e propria è affidata a imagewebp(), che accetta la risorsa, la destinazione (un percorso, uno stream o null per l'output diretto) e la qualità da 0 a 100. Con IMG_WEBP_LOSSLESS al posto della qualità si ottiene la compressione senza perdita.
<?php
// src/WebpEncoder.php
declare(strict_types=1);
namespace App\Image;
use GdImage;
use RuntimeException;
final class WebpEncoder
{
public static function save(GdImage $image, string $target, int $quality = 80): int
{
// Scrive su un file temporaneo e lo rinomina: nessuno legge un file a metà
$temporary = $target . '.' . getmypid() . '.tmp';
if (!imagewebp($image, $temporary, $quality)) {
@unlink($temporary);
throw new RuntimeException("Codifica WebP fallita: {$target}");
}
rename($temporary, $target);
return (int) filesize($target);
}
public static function saveLossless(GdImage $image, string $target): int
{
return self::save($image, $target, IMG_WEBP_LOSSLESS);
}
public static function toString(GdImage $image, int $quality = 80): string
{
ob_start();
imagewebp($image, null, $quality);
return (string) ob_get_clean();
}
public static function isFlatGraphic(GdImage $image, int $sampleStep = 8, int $maxColors = 256): bool
{
// Stima i colori distinti campionando la griglia: le grafiche ne hanno pochi
$colors = [];
$width = imagesx($image);
$height = imagesy($image);
for ($y = 0; $y < $height; $y += $sampleStep) {
for ($x = 0; $x < $width; $x += $sampleStep) {
$colors[imagecolorat($image, $x, $y)] = true;
if (count($colors) > $maxColors) {
return false;
}
}
}
return true;
}
}
La funzione isFlatGraphic() è un'euristica: se campionando l'immagine si trovano pochi colori distinti, si tratta quasi certamente di un logo, un'icona o una schermata, per i quali la compressione senza perdita evita gli aloni attorno ai bordi netti e spesso produce persino un file più piccolo. Con le fotografie vale il contrario: la modalità senza perdita conserva anche il rumore del sensore e genera file più pesanti dell'originale JPEG.
Mettendo insieme caricamento e codifica otteniamo uno script che sceglie la strategia in base al contenuto:
<?php
// convert.php
declare(strict_types=1);
require __DIR__ . '/src/ImageLoader.php';
require __DIR__ . '/src/WebpEncoder.php';
use App\Image\ImageLoader;
use App\Image\WebpEncoder;
[, $source, $target] = $argv + [null, 'foto.jpg', 'foto.webp'];
$image = ImageLoader::load($source);
$bytes = WebpEncoder::isFlatGraphic($image)
? WebpEncoder::saveLossless($image, $target)
: WebpEncoder::save($image, $target, 80);
printf("%s: %d KB -> %s: %d KB\n", $source, filesize($source) / 1024, $target, $bytes / 1024);
A differenza di libvips o di Pillow, GD non espone i parametri avanzati dell'encoder come lo sforzo di compressione o la qualità del canale alfa: usa i valori predefiniti di libwebp. Per la maggior parte dei siti è sufficiente; quando serve un controllo più fine, entra in gioco Imagick.
Ridimensionare e generare le varianti
Servire un'immagine da 4000 pixel a uno smartphone è uno spreco di banda. La soluzione standard è generare un piccolo insieme di larghezze e lasciare scegliere al browser tramite srcset. In GD il ridimensionamento di qualità si ottiene con imagecopyresampled() su una nuova immagine truecolor, avendo cura di preparare un fondo trasparente se la sorgente ha l'alfa.
<?php
// src/Variants.php
declare(strict_types=1);
namespace App\Image;
use GdImage;
final class Variants
{
public const WIDTHS = [320, 640, 960, 1280, 1920];
public static function resize(GdImage $source, int $width): GdImage
{
$height = (int) round(imagesy($source) * $width / imagesx($source));
$target = imagecreatetruecolor($width, $height);
// Fondo completamente trasparente e alfa conservato
imagealphablending($target, false);
imagesavealpha($target, true);
imagefill($target, 0, 0, imagecolorallocatealpha($target, 0, 0, 0, 127));
imagecopyresampled($target, $source, 0, 0, 0, 0, $width, $height, imagesx($source), imagesy($source));
return $target;
}
/**
* @return list<array{width: int, path: string}>
*/
public static function create(string $sourcePath, string $outputDir): array
{
if (!is_dir($outputDir)) {
mkdir($outputDir, 0775, true);
}
$source = ImageLoader::load($sourcePath);
$name = pathinfo($sourcePath, PATHINFO_FILENAME);
$variants = [];
foreach (self::WIDTHS as $width) {
// Nessuna variante più grande dell'originale
if ($width > imagesx($source)) {
break;
}
$path = "{$outputDir}/{$name}-{$width}.webp";
WebpEncoder::save(self::resize($source, $width), $path, $width <= 640 ? 75 : 80);
$variants[] = ['width' => $width, 'path' => $path];
}
return $variants;
}
/**
* @param list<array{width: int, path: string}> $variants
*/
public static function srcset(array $variants, string $publicPath): string
{
return implode(', ', array_map(
static fn (array $v): string => sprintf('%s/%s %dw', $publicPath, basename($v['path']), $v['width']),
$variants,
));
}
}
Il valore 127 di imagecolorallocatealpha() corrisponde alla trasparenza totale: in GD il canale alfa va da 0, opaco, a 127, trasparente, al contrario della convenzione usata quasi ovunque. L'orientamento EXIF è già stato applicato da ImageLoader, quindi la larghezza confrontata con le varianti è quella reale. Nel template il risultato si usa così:
<?php $variants = \App\Image\Variants::create('uploads/foto.jpg', 'public/media'); ?>
<img src="/media/foto-1280.webp"
srcset="<?= htmlspecialchars(\App\Image\Variants::srcset($variants, '/media')) ?>"
sizes="(max-width: 700px) 100vw, 700px"
alt="Descrizione della foto" loading="lazy">
Imagick: controllo fine e animazioni
Imagick espone tutte le opzioni dell'encoder WebP di ImageMagick tramite setOption() con il prefisso webp:, e soprattutto gestisce le immagini a più fotogrammi, cosa che GD non sa fare: imagecreatefromwebp() non legge i WebP animati e imagecreatefromgif() carica solo il primo fotogramma di una GIF.
<?php
// src/ImagickWebp.php
declare(strict_types=1);
namespace App\Image;
use Imagick;
final class ImagickWebp
{
public static function convert(string $source, string $target, int $quality = 80, bool $lossless = false): void
{
$image = new Imagick($source);
try {
self::orient($image);
// Rimuove EXIF, XMP e commenti, ma conserva il profilo colore
$profiles = $image->getImageProfiles('icc', true);
$image->stripImage();
if (isset($profiles['icc'])) {
$image->profileImage('icc', $profiles['icc']);
}
$image->setImageFormat('webp');
$image->setImageCompressionQuality($quality);
$image->setOption('webp:method', '6');
$image->setOption('webp:lossless', $lossless ? 'true' : 'false');
$image->setOption('webp:alpha-quality', '90');
$image->writeImage($target);
} finally {
$image->clear();
}
}
public static function animatedGifToWebp(string $source, string $target, int $quality = 75): void
{
$gif = new Imagick($source);
try {
// Ricostruisce ogni fotogramma completo, perché le GIF memorizzano spesso solo le differenze
$frames = $gif->coalesceImages();
foreach ($frames as $frame) {
$frame->setImageFormat('webp');
$frame->setImageCompressionQuality($quality);
}
$frames->setOption('webp:method', '4');
$frames->setOption('webp:lossless', 'false');
// Permette all'encoder di mescolare fotogrammi con e senza perdita
$frames->setOption('webp:mixed', 'true');
// Il secondo argomento produce un unico file con tutti i fotogrammi
$frames->writeImages($target, true);
$frames->clear();
} finally {
$gif->clear();
}
}
private static function orient(Imagick $image): void
{
match ($image->getImageOrientation()) {
Imagick::ORIENTATION_BOTTOMRIGHT => $image->rotateImage('none', 180),
Imagick::ORIENTATION_RIGHTTOP => $image->rotateImage('none', 90),
Imagick::ORIENTATION_LEFTBOTTOM => $image->rotateImage('none', -90),
default => null,
};
$image->setImageOrientation(Imagick::ORIENTATION_TOPLEFT);
}
}
Alcuni dettagli pratici. coalesceImages() è indispensabile con le GIF ottimizzate, in cui ogni fotogramma contiene solo la porzione che cambia rispetto al precedente: senza questo passaggio il WebP risultante mostrerebbe frammenti scomposti. I ritardi tra i fotogrammi e il numero di ripetizioni vengono ereditati dalla GIF. Infine, ImageMagick ha limiti di risorse propri, configurabili in policy.xml o con Imagick::setResourceLimit(): su un server che elabora caricamenti degli utenti vanno impostati con valori prudenti.
Se l'applicazione è basata su Laravel o su un altro framework con Composer, vale la pena considerare Intervention Image, che offre un'API fluente sopra GD o Imagick e include la codifica WebP. I concetti di questo articolo, dall'orientamento all'alfa fino alla negoziazione dei contenuti, restano gli stessi.
Caricamenti sicuri
Ogni immagine caricata è un input ostile fino a prova contraria. Il rischio più insidioso con GD è la memoria: per decodificare un'immagine GD alloca circa quattro byte per pixel, e un file WebP o PNG di pochi kilobyte può dichiarare dimensioni da centinaia di megapixel. Il risultato è un errore fatale per esaurimento del memory_limit o, peggio, un server che rallenta per tutti. Il controllo va fatto prima della decodifica, leggendo solo l'intestazione.
<?php
// src/UploadProcessor.php
declare(strict_types=1);
namespace App\Image;
use RuntimeException;
final class UploadProcessor
{
private const MAX_BYTES = 15 * 1024 * 1024;
private const MAX_PIXELS = 25_000_000;
private const MAX_SIDE = 2560;
private const ALLOWED = [IMAGETYPE_JPEG, IMAGETYPE_PNG, IMAGETYPE_WEBP, IMAGETYPE_GIF];
/**
* @param array{tmp_name: string, error: int, size: int} $file elemento di $_FILES
*/
public static function handle(array $file, string $targetDir): string
{
if ($file['error'] !== UPLOAD_ERR_OK || !is_uploaded_file($file['tmp_name'])) {
throw new RuntimeException('Caricamento non valido');
}
return self::process($file['tmp_name'], $targetDir);
}
public static function process(string $path, string $targetDir): string
{
if (filesize($path) > self::MAX_BYTES) {
throw new RuntimeException('File troppo grande');
}
// getimagesize legge solo l'intestazione: nessun pixel viene decodificato
$info = @getimagesize($path);
if ($info === false || !in_array($info[2], self::ALLOWED, true)) {
throw new RuntimeException('Formato non ammesso');
}
if ($info[0] * $info[1] > self::MAX_PIXELS) {
throw new RuntimeException('Dimensioni eccessive');
}
$webp = WebpInfo::fromFile($path);
if ($webp?->animated) {
throw new RuntimeException('Le animazioni richiedono una pipeline dedicata');
}
$image = ImageLoader::load($path);
$longest = max(imagesx($image), imagesy($image));
if ($longest > self::MAX_SIDE) {
$width = (int) round(imagesx($image) * self::MAX_SIDE / $longest);
$image = Variants::resize($image, $width);
}
// Il nome del file è generato dal server, mai preso dal client
$target = sprintf('%s/%s.webp', rtrim($targetDir, '/'), bin2hex(random_bytes(16)));
WebpEncoder::save($image, $target, 82);
return $target;
}
}
La riscrittura completa dell'immagine con GD ha un effetto collaterale benefico: il file salvato contiene solo pixel, senza EXIF, coordinate GPS, commenti o dati accodati in fondo al file. È anche una difesa contro i file poliglotti, costruiti per essere al tempo stesso un'immagine valida e uno script. Il nome casuale generato con random_bytes() elimina alla radice i problemi di percorso e di collisione.
Negoziazione del formato con un front controller
Quando gli originali restano in JPEG e PNG, uno script PHP può servire WebP ai browser che lo dichiarano nell'intestazione Accept e il formato originale agli altri. Due accorgimenti sono obbligatori: l'intestazione Vary: Accept, senza la quale una CDN potrebbe servire WebP a un client che non lo legge, e un controllo rigoroso del percorso richiesto.
<?php
// public/image.php
declare(strict_types=1);
require __DIR__ . '/../src/ImageLoader.php';
require __DIR__ . '/../src/WebpEncoder.php';
use App\Image\ImageLoader;
use App\Image\WebpEncoder;
const MEDIA_DIR = __DIR__ . '/../media';
const CACHE_DIR = __DIR__ . '/../cache';
const SOURCE_TYPES = ['jpg' => 'image/jpeg', 'jpeg' => 'image/jpeg', 'png' => 'image/png'];
function acceptsWebp(string $accept): bool
{
foreach (explode(',', $accept) as $part) {
$params = array_map('trim', explode(';', $part));
if (strtolower(array_shift($params)) === 'image/webp') {
// Un fattore di qualità pari a zero significa rifiuto esplicito
return !in_array('q=0', $params, true);
}
}
return false;
}
function serve(string $path, string $type): never
{
header('Content-Type: ' . $type);
header('Content-Length: ' . filesize($path));
header('Cache-Control: public, max-age=86400');
header('Vary: Accept');
readfile($path);
exit;
}
$requested = (string) ($_GET['path'] ?? '');
$mediaRoot = realpath(MEDIA_DIR);
$source = realpath(MEDIA_DIR . '/' . $requested);
$extension = strtolower(pathinfo((string) $source, PATHINFO_EXTENSION));
// realpath risolve ../ e collegamenti: il file deve restare dentro la cartella media
if ($source === false || !str_starts_with($source, $mediaRoot . DIRECTORY_SEPARATOR) || !isset(SOURCE_TYPES[$extension])) {
http_response_code(404);
exit;
}
if (!acceptsWebp($_SERVER['HTTP_ACCEPT'] ?? '')) {
serve($source, SOURCE_TYPES[$extension]);
}
$relative = substr($source, strlen($mediaRoot) + 1);
$cached = CACHE_DIR . '/' . preg_replace('/\.\w+$/', '.webp', $relative);
if (!is_file($cached) || filemtime($cached) < filemtime($source)) {
if (!is_dir(dirname($cached))) {
mkdir(dirname($cached), 0775, true);
}
// Un lock esclusivo evita conversioni duplicate in caso di richieste simultanee
$lock = fopen($cached . '.lock', 'c');
flock($lock, LOCK_EX);
clearstatcache(true, $cached);
if (!is_file($cached) || filemtime($cached) < filemtime($source)) {
WebpEncoder::save(ImageLoader::load($source), $cached, 80);
}
flock($lock, LOCK_UN);
fclose($lock);
}
serve($cached, 'image/webp');
Il file .lock resta accanto alla versione in cache dopo la prima conversione: è vuoto e innocuo, e riutilizzarlo evita di doverlo ricreare a ogni rigenerazione. Con Nginx lo script può restare dietro una regola di riscrittura, mentre l'intestazione Vary e i file già convertiti possono essere serviti direttamente dal web server per le richieste successive. Una configurazione che prova prima il file in cache e ricorre a PHP solo quando manca è la seguente:
map $http_accept $webp_suffix {
default "";
"~image/webp" ".webp";
}
location ~* ^/media/(?<image>.+)\.(jpe?g|png)$ {
add_header Vary Accept;
try_files /cache/$image$webp_suffix /media/$image.$2 =404;
}
In questo schema i file WebP vanno generati in anticipo, per esempio con lo script del paragrafo seguente, rispettando la struttura delle cartelle: media/foto.jpg diventa cache/foto.webp.
Conversione in blocco da riga di comando
Per convertire un archivio esistente conviene uno script CLI, che non ha i limiti di tempo delle richieste web. Con GD la memoria si libera da sola quando l'oggetto GdImage esce dallo scope, ma è utile mostrarne l'andamento per accorgersi di eventuali anomalie su archivi grandi.
<?php
// bin/convert-tree.php
declare(strict_types=1);
require __DIR__ . '/../src/ImageLoader.php';
require __DIR__ . '/../src/WebpEncoder.php';
use App\Image\ImageLoader;
use App\Image\WebpEncoder;
if ($argc < 3) {
fwrite(STDERR, "Uso: php bin/convert-tree.php <sorgente> <destinazione>\n");
exit(2);
}
[, $sourceDir, $targetDir] = $argv;
$sourceDir = rtrim((string) realpath($sourceDir), '/');
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($sourceDir, FilesystemIterator::SKIP_DOTS));
$converted = $failed = $saved = 0;
foreach ($iterator as $file) {
if (!$file->isFile() || !in_array(strtolower($file->getExtension()), ['jpg', 'jpeg', 'png'], true)) {
continue;
}
$relative = substr($file->getPathname(), strlen($sourceDir) + 1);
$target = $targetDir . '/' . preg_replace('/\.\w+$/', '.webp', $relative);
// Salta i file già convertiti e aggiornati
if (is_file($target) && filemtime($target) >= $file->getMTime()) {
continue;
}
try {
if (!is_dir(dirname($target))) {
mkdir(dirname($target), 0775, true);
}
$image = ImageLoader::load($file->getPathname());
$bytes = WebpEncoder::isFlatGraphic($image)
? WebpEncoder::saveLossless($image, $target)
: WebpEncoder::save($image, $target, 80);
$saved += $file->getSize() - $bytes;
$converted++;
printf("%s (%d MB in uso)\n", $relative, memory_get_usage(true) / 1048576);
} catch (Throwable $error) {
$failed++;
fwrite(STDERR, "Errore su {$relative}: {$error->getMessage()}\n");
}
}
printf("Convertiti: %d, falliti: %d, risparmiati: %d KB\n", $converted, $failed, $saved / 1024);
exit($failed > 0 ? 1 : 0);
Il codice di uscita diverso da zero in caso di errori permette di usare lo script in una pipeline di deploy o in un job pianificato e di accorgersi dei fallimenti. Su macchine con molti core si possono lanciare più istanze su sottocartelle diverse, oppure usare xargs -P per distribuire il lavoro.
Conclusioni
In PHP la gestione di WebP è alla portata di qualsiasi installazione con GD, a patto di conoscerne le peculiarità: la conversione obbligatoria delle immagini a tavolozza, la gestione esplicita dell'alfa con la sua scala invertita, l'orientamento EXIF da applicare a mano, l'assenza di supporto alle animazioni. Imagick colma queste lacune con un controllo completo sull'encoder e la gestione dei fotogrammi multipli, al prezzo di una dipendenza in più. Attorno alla conversione restano le pratiche che fanno la differenza in produzione: controllare le dimensioni prima di decodificare, non fidarsi mai di estensioni e nomi forniti dal client, rispondere con Vary: Accept e scrivere i file in modo atomico. Il parser dell'intestazione, infine, mostra quanto il formato sia semplice da interrogare: trenta byte e qualche unpack() bastano per sapere di che immagine si tratta.