V PHP byl dlouho hegemonem Phing. Ten mi ovšem z mnoha důvodů nikdy nevyhovoval, i proto, že jde o nástroj, který svými možnostmi ustrnul hluboko v minulé dekádě. Například konfigurace v XML je čirý masochismus. A zápisy běžných jazykových statementů jako if, try-catch, apod., do jakéhokoliv dokumentu, nebudou nikdy tak efektivní, jako vyjádření přímo v kódu. Vyzkoušel jsem i pár dalších nástrojů, například TaskPHP, ale nepokrývaly mé potřeby.

Pohrával jsem i s myšlenkou, že bych pro build PHP použil Gulp, nebo něco z ekosystému Javascriptu, ale v okamžiku, kdy build potřebuje použivat struktury v PHP, tak by to nefungovalo. Nezbylo, než si napsat vlastní tool: Genesis.

Genesis

Genesis se skládá jen z několika tříd a snaží se stát na jednoduchosti – build je vyjádřen přímo (viz níže). Jde o třídu, která má libovolné množství tasků = public metod runXyz(). Což přináší výhodu plného využití objektového návrhu – dědičnost, kompozici, apod. Jaká třída se pro build použije si zvolíte v konfiguraci, pouze musí implementovat jednoduché rozhraní Genesis\IBuild.

class Build extends Genesis\Build
{

   public function runInit()     
   {
        // commands here
   }

}

Samotný příkaz v CLI je jednoduchý:

genesis <nazev-tasku> <volitelny-dalsi-argument>

např. tedy:

genesis init dev

Zavolá v build třídě metodu runInit(), přičemž argumenty ‘init’ a ‘dev’ se předají také a je možné s nimi pracovat.

Lze použít parametr ‘–working-dir’, který umožní spustit build v jiném, než aktuálním adresáři. V konfiguračním kontejneru je vždy dostupná proměnná ‘workingDirectory’, která je vždy naplněná cestou k aktuálnímu pracovnímu adresáři.

Sestavování aplikace obnáší spoustu úkolů, kde je nejlepší využít proměnné, protože například seznam adresářů k vytvoření, nebo cestu k executable PHPUnitu nechceme mít natvrdo zadrátovanou v kódu. Pro uložení konfigurace se pro jeho jednoduchost používá formát neon, známý z Nette Frameworku, přičemž podporuje proměnné, podobně jako v Nette.

Ukázkový jednoduchý build

Build potřebuje vlastně jen dvě věci: třídu se samotným buildem a konfigurační soubor.

config.neon

class: Build # naše třída
publicDirectory: %workingDirectory%/../public # proměnná workingDirectory je vždy naplněná
directoriesToCreate:
  "%publicDirectory%/data": "0777"
  "%publicDirectory%/data/files": "0777"

Build.php

class Build extends Genesis\Build
{

   public function runInit()
   {
        $this->logSection('Create directories and files.');
        foreach ($this->container->directoriesToCreate as $directory => $chmod) {
             $command = new Commands\Filesystem\Directory();
             $command->create($directory, $chmod);
        }
   }
}

Volitelně může být v pracovním adresáři soubor bootstrap.php, který se dá použít k zajištění autoloadingu, integraci s vaší aplikací (o tom dále), nebo k čemukoliv jinému. Aktuální example na Githubu.

Integrace s PHP aplikací a jejími službami

U složitějších aplikací je nezbytné, aby se buildovací proces dostal k některým službám z aplikace. Například v Nette Framework si v DI kontejneru vytvoříte databázové spojení, které bude build také potřebovat.

$container  = require_once __DIR__ . '/../app/bootstrap.php'; # načteme bootstrap frameworku

$configContainer = new Genesis\Config\Container();
$configContainer->databaseConnection = $container->databaseConnection;
return $configContainer;

Pokud bootstrap.php z pracovního adresáře buildu vrátí instanci třídy Genesis\Config\Container, tak se spojí s obsahem kontejneru generovaného ze souboru config.neon.

Pokud vás nástroj zaujal, můžete si ho snadno vyzkoušet. Na Githubu je example project a vyzkoušení je otázka několika příkazů během pár sekund.

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

Na půdě Media se v sobotu dopoledne sešla hromada vynikajících programátorů. Pro začátek bez jakékoliv určité představy o tom, co vlastně budou dělat. Kupodivu to příliš nevadilo, ukázalo se, že domluvit se umíme. Z hlediska uživatelského rozhraní se nám stal inspirací web s doplňky MooTools a z funkčního repozitář PHP knihoven Packagist.

Pohled do naší programátorské kuchyňky

Jako pracovní nástroj jsme zvolili pochopitelně Nette Framework. Přestože každý z nás má nějaké osvědčené postupy, jak v něm pracovat, dohodli jsme se, že se budeme držet běžných doporučených cest známých z dokumentace. Spoustu z nás čekala první větší zkušenost s Nette\Database. Nepoužili jsme žádné přídavné doplňky. Přece se nebudeme spolu dohadovat, proč že se použil plugin tvůj a ne ten můj, který je přece lepší!

Zdrojové kódy jsme verzovali pochopitelně pomocí Gitu a naše práce byla průběžně k vidění na GitHubu. Došlo nám i několik pull requestů. Doufejme, že jich ještě v budoucnu spousta dorazí.

Vývoj probíhal velice živelně. Commity přibývaly jeden za druhým, takže neocenitelným pomocníkem se nám stal příkaz git pull --rebase, který bylo nutné zavolat před každým pokusem o push. Rozdělení práce probíhalo velice demokraticky, ale kupodivu naprosto bezproblémově. Ukázalo se, že máme mezi sebou specialisty na GitHub API, na Composer, na Bootstrap, případně na všechno, takže jsme si nekonkurovali.

Kvůli velkému počtu změn v architektuře se příliš nedařilo psát testy (což je jinak v prostorách Media nemyslitelné). Druhý den, v neděli, se ale prokázalo, že na testech je těžké jen začít a pár unit a selenium testů v projektu přibylo.

Pro rychlé prototypování nám byl užitečný CSS framework Bootstrap. Jestli zůstane i ve finální verzi zatím nevíme. Záleží na tom, jestli se ho povede přemluvit, aby nevypadal jako Twitter.

Na novém webu účastníci začali pracovat od 11 hodin v sobotu. Cca v 11 hodin dorazil i David Grudl, jen bych taktně pomlčel o tom, podle kterého časového pásma si nařídil hodinky. S programováním se končilo až někdy v půl páté nad ránem. Pak se dal krátký spací rozchod a v neděli v 11 byl opět sraz a ještě se několik hodin zmáklo. Byť mému biorytmu to příliš nesedlo, tak jsem se na vlastní oči přesvědčil, že pověsti o nočním životě programátorů se 100 % zakládají na pravdě.

Výsledek

Nette Addons!

Výsledkem je z mého pohledu reprezentativní aplikace, která umí přehledně zobrazovat doplňky, spravovat jejich verze a závislosti na dalších doplňcích. Nabízí perfektní provázání se současnou Nette komunitou – funguje přihlašování uživatelů registrovaných přes fórum, umožňuje hodnocení přihlášenými uživateli. Doplňky lze téměř bezpracně importovat z GitHubu, což je defacto standard pro hostování open source softwaru. Systém umí přednačíst název z názvu GitHub repozitáře, další metadata ze souboru composer.json pro PHP balíčkovací systém Composer a popis doplňku ze souboru readme.*. Z mého pohledu snad nejužitečnější funkcí je to, že nové Nette Addons bude poskytovat soubory s metadaty pro Composer, takže kterýkoliv doplněk Nette půjde tímto perfektním nástrojem snadno nainstalovat přes příkazovou řádku.

Malé video představení

Pro demonstraci používá jednoduchou aplikaci. Ta je vedle samotného testování zajímavá ještě v jednom ohledu. Jedná se totiž o konkrétní implementaci obecné architektury, kterou nedávno popisoval Vašek Purchart ve svém článku Architektura aplikace nad Doctrine 2. Veškerá aplikační logika je přenesena z presenterů do fasády, do budoucna tak například umožňuje snadno přidat více různých rozhraní, jako je konzole nebo mobilní aplikace.

Ukázková aplikace využívá čisté dependency injection, což mimo jiné usnadňuje právě testovatelnost. Ve své přednášce k tomu Dan poznamenává: „V Nette jsou jen tři místa, kde byste měli používat kontejner jako service locator. Je to bootstrap, presenter loader respektive presenter factory a testy. Nikde jinde byste napřímo s kontejnerem pracovat neměli.“

Pokud vás téma návrhu a testovatelnosti webových aplikací zaujalo, navštivte naše školení Pokročilý vývoj a testování aplikací.

Jaké máte vy zkušenosti s testováním presenterů/controllerů a obecně celého životního cyklu požadavku? Testujete i je, nebo se omezujete jen na testování dílčích tříd a izolovaných funkčností?