Těžko budete nutit klienta, aby každý obrázek před nahráním zmenšil a ořízl na velikost odpovídající zobrazení na webu. Už vůbec ne na všechny velikosti, které na webu používá. A co když přidáte další zobrazení? Nebo se změní stávající velikosti kvůli redesignu? Zmenšovat obrázky jen přes HTML je pak neuctivé k času načítání stránky a majitelům mobilních FUP. Jak elegantně to děláme u nás?

Malá lákací ukázka: zobrazení obrázku na titulce jednoho našeho projektu vypadá v kódu takto:

{$performance->getImage() |thumbnail:large |imagehtml, $performance->getDescription()}

Ano, správně, je to zápis v šablonovacím jazyce Latte. Getter $performance->getImage() vrací, tadá, instanci třídy Image, kterou jsme si popsali v předchozím článku. Ta se předá šablonovacímu filtru (v dřívějších verzích Nette se filtrům říkalo helpery) thumbnail, spolu s klíčem, který obsahuje informaci o tom, jaké změny před zobrazením na obrázku použít. Ten vrátí cestu k souboru na disku a předá ji filtru imagehtml, který cestu zkrátí na URL, vytvoří HTML tag, cestu mu nastaví do atributu src, a popisek z $performance->getDescription() do atributu alt. Elegantněji už to snad ani nejde.

Rozeberme si to teď trochu podrobněji. Filtr thumbnail volá třídu ThumbnailGenerator. Ta krom instance IFileRepository a instance IImageFileNamingStrategy dostane pole klíčů jednotlivých velikostí obrázků používaných v dané aplikaci. Třeba z konfigurace.

imageSizes:
	square:
		width: 150
		height: 150
		flag: crop
	large:
		width: 960
		height: 960
		flag: fit

Atributy width a height jsou jasné, vlajky flag používáme tři: fit vsouká obrázek do daných rozměrů a nikdy jej nezvětšuje, crop jej na ně ořízne. Pofiderní vlajka enlarge funguje jako fit, ale vsouká obrázek na dané rozměry, i kdyby byl sebemenší.

Klíče nám slouží jen pro pohodlnější určení varianty zmenšení a předávání parametru v šabloně (viz poznámky). Klidně bychom mohli předávat přímo trojici argumentů, ale takto alespoň víme, co se všechno v aplikaci používá, máme to přehledně na jednom místě a bráníme divokým vývojářům v přílišném rozletu.

Pak se nám bude hodit metoda getThumbnailName(), o kterou obohatíme rozhraní IImageFileNamingStrategy, potažmo v našem konkrétním případě jeho implementaci HashFileNamingStrategy. Ta bude přes ThumbnailGenerator vracet jméno souboru zmenšeniny obrázku, podle cesty k originálu a zadaných parametrů. Parametry jsme podle klíče z šablony našli v konfiguraci.

public function getThumbnailKey($path, $width, $height, $flag)
{
	// rozparsujeme jméno původního souboru pomocnou metodou
	$infoFromOriginalPath = $this->getInfoFromOriginalPath($path);
	
	$imageId = $infoFromOriginalPath['id'];
	$md5 = $infoFromOriginalPath['hash'];

	$sizes = $width . 'x' . $height . '-' . $flag;

	$key = $md5
			. '-' . $imageId
			. '-' . $sizes
			. '.'
			. strtolower(pathinfo($path, PATHINFO_EXTENSION));
	return $key;
}

Tím dostaneme z cesty k souboru, který jsme si uložili, a klíče large jméno souboru.

2f/25/2f2555d95ee03f950c9ddae2f1692c55-42-960x960-fit.jpg

Ten předáme šabloně a ta ho (po úpravách filesystémové cesty na korektní URL s cestou k obrázkům) vypíše na výstup. A máme hotovo.

…cože? Že jsme nikde nevytvořili samotnou zmenšeninu obrázku? Správně, nevytvořili. Starat se o vytváření všech zmenšenin při uploadu je zbytečně náročné. Navíc některým nahraným obrázkům se nikdy nemusejí vytvořit všechny možné velikosti. A znovu – co když variantu přidáme? Museli bychom projít všechny originály a variantu jim vytvořit ad hoc.

Ne, vytvoření raději necháme na aplikaci spolu s chytrým rewritem a/nebo routou.

Jak obrázkům vytváříme zmenšeniny

Pokud už soubor s požadovaným obrázkem na disku existuje, vrátí ho webový server rovnou. Nespouští se vůbec žádné PHP s nějakým Nette a vším tím overheadem okolo. Prostě se ze serveru vydá statický soubor.

Co se ale stane, když se uživatel pokusí přistoupit ke zmenšenině obrázku, která ještě na serveru není? Využijeme teď toho, že se frameworku předávají všechny požadavky na přístup k cestám, které na serveru fyzicky neexistují.

Zásadní technikou zpracování požadavků frameworkem je přesměrování všech potřebných volání na jednotný vstupní bod – v případě Nette je to soubor index.php. Ten pak už požadavky zpracuje interně.

$this[] = new Route('/<? [a-z0-9]{2}>/<? [a-z0-9]{2}>/<key (.*)>', array(
	'module' => 'Front',
	'presenter' => 'ImageService',
	'action' => 'default',
));

Toto je routa Nette Frameworku, která požadavky na neexistující zmenšeniny posílá speciálnímu presenteru ImageServicePresenter, který:

• metodou v HashFileNamingStrategy z parametru $key zrekonstruuje informace o zmenšenině,
• zkontroluje, jestli je kombinace vlastností zmenšeniny platná, tedy dostupná v nastavení (určitě bychom nechtěli, aby nám nějaký vtipálek pustil generování všech možných kombinací velikostí a vlajek),
• zkontroluje, jestli existuje entita, pro kterou má zmenšeninu vytvořit,
• pro jistotu ověří existenci originálního souboru,
• vytvoří zmenšeninu podle zadaných kritérií, uloží ji na disk a vrátí její data (aby je uživatel viděl přímo ve svém požadavku).

Pokud jakákoliv z kontrol neprojde, vrací požadavek chybu 404.

Při dalším pokusu o přístup k té samé zmenšenině už server vrátí rovnou její statickou variantu, protože soubor fyzicky existuje.

Poznámky z jedné kapsy

K výše zmíněným jménům souboru jsme došli přes několik iterací. Původně jsme měli název originálu jako čistý MD5 hash a jméno souboru zmenšeniny jako jiný MD5 hash. Což je sice zvenku možná krásně čisté, aplikace se o to postará, ale pro debugování je to peklo.

Proto jsme do jména originálu přidali ID souboru (poznámka o kolizích byl jen lehký trolling), abychom mohli lépe dohledat, ke které entitě soubor patří.

Soubory se i celkem jednoduše procházejí běžnými konzolovými nástroji jako find, takže není problém třeba promazat ty, jejichž parametry už nevyhovují nastavení projektu.

Jedna ze slepých cestiček také byla místo trojice výška/šířka/vlajka ukládat do jména souboru jen klíč, ale záhy jsme zjistili, že pak soubory budou vyhnívat, můžou vznikat nepotřebné duplicitní soubory, při změně parametrů klíče se musí původní soubory ručně promazat, jinak se nenavytváří znovu, a jiné.

Co může být problém je změna velikosti obrázku na nějaké hodně navštěvované stránce – server pak začne generovat víc zmenšenin než běžně a může ho to i zabít. Pak je na pořadu dne zmenšeniny navytvářet nějakým workerem bokem v době, kdy není zátěž na serveru taková.

Při práci se jmény souborů používáme všude absolutní cesty.

Samozřejmě se může stát, že getter nevrátí instanci Image – nemusí být pro $performance povinná. Proto vypadá šablona častěji nějak takto:

{if $performance->getImage()}
	{$performance->getImage() |thumbnail:large |imagehtml, $performance->getDescription()}
{else}
	{NULL |dummyimagehelper:large |imagehtml}
{/if}

dummyimagehelper vrací dummy obrázky připravené specificky pro náš projekt. Ať už jsou vytvořené pro jednotlivé varianty zmenšenin ručně, nebo ať už je necháváme generovat z nějakého předpřipraveného zdroje podobně, jako zmenšeniny skutečných originálů.

Související články

• Matěj Humpál: Jak ukládáme obrázky

Řekněme, že každý obrázek (abychom o nich někde měli přehled a mohli k nim mít i nějaká metadata) je zastoupen entitou Image. Ta nejjednodušší může vypadat třeba nějak takto (pro ještě větší zjednodušení vynechávám gettery, settery a další):

class Image
{
	private $id;
	private $filename;
	private $extension;
}

Abychom vytvořili vztah mezi naší entitou uloženou v jednom úložišti (typicky v databázi) a samotným souborem obrázku uloženým v jiném úložišti (disk, cloud, co si představíte), vytvoříme si třídu ImageRepository. Takto může vypadat:

class ImageRepository
{
	/** @var IFileRepository */
	private $fileRepository;

	/** @var IImageFileNamingStrategy */
	private $fileNamingStrategy;
	
	public function save(Image $image, $data)
	{
		return $this->fileRepository->save(
			$this->fileNamingStrategy->getOriginalName($image),
			$data
		);
	}
}

Podívejme se na dvě závislosti třídy. $fileNamingStrategy je z nich trochu záhadnější. Protože každá instance projektu (nebo, řekněme, klient) může mít jiné požadavky na pojmenování souborů, implementují si po svém rozhraní IImageFileNamingStrategy s metodou getOriginalName. Například takto:

class HashFileNamingStrategy implements IImageFileNamingStrategy
{
	public function getOriginalName(Image $image)
	{
		return md5($image->getId() . $image->getFilename())
			. '-' . $image->getId() 
			. '.' . $image->getExtension();
	}
}

Nebojte se, nehashujeme hesla. MD5 je tady jako hashovací algoritmus víceméně v pohodě. Aby bylo všemu učiněno zadost a nedostali jsme nedejbože duplicitní jméno souboru pro jinou instanci Image kvůli kolizi v algoritmu (oči divoce protáčející smajlík), můžeme do nezahashované části jména souboru přidat ID entity.

Dostaneme tak jméno souboru, které vypadá třeba takhle:

2f2555d95ee03f950c9ddae2f1692c55-42.jpg

Závislost IFileRepository je nasnadě – o úroveň nižší repozitář, který volá funkce samotného úložiště, čtení, ukládání, zjištění existence souboru – ten nepotřebuje vědět nic o tom, že pracuje s třídou Image, a zároveň odstiňuje ImageRepository od konkrétní implementace ukládání – jeho výměnou (u nás typicky změnou jednoho řádku v konfiguraci DI kontejneru) můžeme vyměnit celé úložiště souborů – třeba z lokálního filesystému na Amazon S3.

Řekněme, že budeme obrázky ukládat do filesystému. FilesystemRepository tedy bude mít jako property nějaký kořenový adresář $rootDir (který každá instance dostane nejlépe jako parametr konstruktoru z konfigurace DI kontejneru).

Soubory na disku je třeba podle něčeho organizovat. Tisíce souborů v jednom adresáři už můžou dát strojům pěkně zabrat – hodí se nám tedy, aby soubory byly nějak rozumně rozloženy. Tady přijde ke cti MD5 začátek jména souboru – FilesystemRepository každý soubor uloží do stuktury podle prvních dvou dvouznaků jeho jména. Máme vyzkoušeno, že se tak soubory do adresářové struktury rozloží pěkně rovnoměrně. 256×256 adresářů should be enough for everyone. Soubor zmíněný výše relativně k $rootDir se uloží takto:

2f/25/2f2555d95ee03f950c9ddae2f1692c55-42.jpg

Podle jména souboru víme, jak ho hledat v adresářové struktuře (kdybychom se chtěli ručně podívat, kde je třeba případný problém) a na konci souboru máme ID jeho entity – to kdyby byl problém na straně modelu.

Metoda save ImageRepository tedy uloží data obrázku. Podle podobného klíče bude v ImageRepository fungovat i vyzvednutí obrázku: předáme instanci Image metodě getPath a dostaneme cestu k souboru. Metoda load pak může vracet zase obrázek jako data.

Originály souborů, v našem případě obrázků, máme uložené na disku, dokážeme podle entity najít cestu k nim a dále s nimi manipulovat. V následujícím článku se podíváme na mnohem zajímavější věc, a to jak s obrázky dále manipulujeme a posíláme je uživatelům.

Související články

• Matěj Humpál: Jak zobrazujeme obrázky