Nové jmenné prostory v Nette

Společně s vydáním Nette Framework 2 beta dochází k úpravě jmenných prostorů a názvů tříd. Je jasné, že přejmenovávání nepatří mezi populární úpravy, nicméně snažil jsem se udělat vše pro to, aby přechod byl bezbolestný.

Jaké jsou vlastně důvody?

Nette Framework je dost možná prvním PHP frameworkem na světě, který používání jmenných prostorů zavedl. Kvůli prodlevám s vydáním PHP 5.3 se začaly v praxi používat docela pozdě a tudíž mají stále svou první a dnes již historickou podobu. Ta neodpovídá současnému stavu frameworku, navíc pojmenování tříd bylo často ovlivněno kompatibilitou s verzí PHP 5.2. Před vydáním nové verze frameworku je záhodno stav napravit.

Zpětná kompatibilita

Úpravy se týkají především verze frameworku pro PHP 5.3. Ve verzích pro 5.2 dochází jen k drobným změnám, a to proto, aby se zbytečně nerozevíraly nůžky mezi 5.3 a 5.2 verzemi.

Nejspíš by k tak radikálním krokům ani nedošlo, kdyby nebylo možné přechod zcela zautomatizovat. K dispozici proto máte skript, který všechny změny ve vašich zdrojových souborech udělá za vás! Najdete jej v distribučním balíku v tools/Code-Migration/class-updater.php.

Parametry pro spuštění:

php class-updater.php -d /cesta/k/app [-f]

kde /cesta/k/app nahradíte za skutečnou cestu ke složce s vašimi zdrojovými soubory. Pokud neuvedete nepovinný parameter -f, skript běží v read-only režimu a jen vypíše, které soubory by změnil.

DŮLEŽITÉ UPOZORNĚNÍ: nezapomeňte si před použitím zazálohovat zdrojové kódy a po konverzi ověřit porovnáním, zda záměny proběhly v pořádku.

Skript vyžaduje pro spuštění PHP 5.3 a najdete jej jen v 5.3 balíku. Lze pomocí něj konvertovat všechny verze Nette Framework (tj. pro 5.3 i pro 5.2).

Pokud z nějakého důvodu nemůžete soubory aktualizovat, můžete využít aliasování tříd. Stačí ve své aplikaci hned po načtení frameworku načíst skript compatibility-aliases.php, který najdete opět v tools/Code-Migration. Příklad v bootstrap.php:

// načteme framework
require LIBS_DIR . '/Nette/loader.php';

// načteme aliasy
require LIBS_DIR . '/compatibility-aliases.php';

Nette\Debug::enable(); // fungují původní názvy tříd

Aliasování funguje pouze pro Nette Framework ve verzi pro PHP 5.3.

Pravidla pojmenování

Novou podobu názvů tříd jsem chtěl podřídit, jako v podstatě vše v Nette, pohodlí programátora. Jak ukázala řada diskusí, subjektivní požadavky mohou být rozporuplné. Pro někoho znamená pohodlí mít co nejkratší názvy tříd, pro jiného jsou to názvy co nejvíce popisné. Přehled myšlenek, ze kterých se vycházelo, najdete v článku Best practices pro jmenné prostory v PHP.

Nyní by všechny třídy měly mít výstižný název i bez uvedení jmenného prostoru, preferovány jsou kratší názvy a lze pěkně využít parciální namespaces:

use Nette\Http; // alias pro namespace

// dostupné jsou všechny třídy via Http:
$request = new Http\Request;
$response = new Http\Response;

Nová struktura pro 5.3

Nejlépe si novou strukturu můžete prohlédnout přímo v API dokumentaci. Důležité změny jsou tyto:

výjimky, které byly bez namespace, jsou nyní v prostoru Nette
Nette\Debug je teď Nette\Diagnostics\Debugger (což je dlouhé, zvažuje se alias např. NDebug)
Presenter & Control jsou ve jmenném prostoru Nette\Application\UI, routery v Nette\Application\Routers
z AppForm se stal Nette\Application\UI\Form
String → Nette\Utils\Strings a ArrayTools → Nette\Utils\Arrays
Finder, Json, Neon, Paginator a Html jsou nyní taky v Nette\Utils (třída Tools už není)
Nette\Mail\Mail → Nette\Mail\Message
prostor Nette\Templates přejmenován na Nette\Templating
ITranslator je nyní v prostoru Nette\Localization
úložiště pro cache jsou v Nette\Caching\Storages
low level komponenty jsou v Nette\ComponentModel

Jak bylo vysvětleno výše, nemusíte se přechodu obávat, konverzi za vás udělá utilitka.

Nová struktura pro 5.2

Zde jsou důležité vlastně jen tyto změny:

Debug → Debugger, String → Strings, ArrayTools → Arrays, MultiRouter → RouteList a DownloadResponse → FileResponse

A pak ještě několik tříd, konverzi opět udělá utilitka.

Přechod na verzi 5.3 se jmennými prostory

PHP ve verzi 5.2 je zatím stále podporováno, ale rozhodně doporučujeme aktualizovat na verzi pro PHP 5.3 se jmennými prostory. S migrací vám pomůže nový nástroj tools/Code-Migration/migrate-53.php. Příkazová řádka i všechny upozornění jsou stejné, jako v případě nástroje class-updater.php. Enjoy!

19. 4. 2011 Nette Komentáře: 6

Best practices pro jmenné prostory v PHP

Pár dobře míněných tipů, jak navrhnout strukturu jmenných prostorů (namespaces) a názvy tříd v PHP 5.3.

Ačkoliv jmenné prostory jsou asi nejznámější novinkou PHP verze 5.3, za tolik klíčové je nepovažuji. Respektive na seznamu přání, co bych rád v PHP viděl, by se mezi první desítku dostaly jen s odřenými oddělovači. Praxe totiž ukazuje, že jmenným konfliktům spolehlivě předejde použití 1–2 písmenného prefixu, stejně tak jsem se nikdy nedopustil názvů tříd jako Zend_Service_DeveloperGarden_Response_ConferenceCall_AddConferenceTemplateParticipantResponseType (97 znaků, zajímalo by mě, jak s tím dodržují pravidlo o max. délce řádků 80 znaků ). Avšak PHP kráčí ve šlépějích Javy a tak tu máme namespaces. Jak s nimi naložit?

Přínos jmenných prostorů

Asi nejsložitější otázka, na kterou si musíte odpovědět, zní: čemu prospěje přejmenovat třídu:

sfForm → Symfony\Component\Form\Form

Otázka je osvědčeným závdavkem k nekonečným flame wars. Z hlediska pohodlí programátora, intuitivnosti a zapamatovatelnosti je vhodnější původní stručné a výstižné sfForm. Odpovídá totiž tomu, jak třídu programátoři označí hovorově, tj. „formulář v symfony“. Nový a delší název je zase správný z jiných hledisek, u nichž si ovšem nejsem jist, jestli je běžný uživatel ocení.

Může se tedy stát, že jmenné prostory budou jednou částí programátorské obce vnímány jako skvělá věc, pro kterou je třeba něco obětovat ve „vyšším zájmu“ (srovnej s XHTML), a druhou částí jako něco, co z dobře uchopitelných frameworků udělalo těžkopádné obludy (a tak jsme se na ně těšili).

Jak jmenné prostory rozvrhnout?

Syntaktickou stránku použití popisuje dokumentace, objevit správné vzory však chce praxi, na kterou zatím nebylo dost času. Prostory v PHP mají svá specifika daná celou řadu faktorů, proto není ideální 100% kopírovat konvence používané třeba v Javě nebo .NET. Dá se z nich však dobře vycházet.

Více si řekneme u jednotlivých pravidel pro pojmenování.

1) třída má mít výstižný název i bez uvedení NS

Název každé třídy i bez jmenného prostoru musí vystihovat její podstatu. Nevhodné by bylo přejmenovat třídu ArrayIterator → Spl\Iterators\Array, protože pod názvem Array by člověk neočekával iterátor (pomiňme, že třídu nelze nazvat klíčovým slovem). A pozor, ani z názvu Spl\Iterators\Array nemusí být zřejmé, že jde o iterátor, protože nelze sázet na to, že namespace Spl\Iterators obsahuje pouze iterátory. Mohou tam být třeba i nějaké pomocné třídy.

Pár příkladů:

nevhodné: Nette\Application\Responses\Download – nelze dovodit, že Download je odpověď
nevhodné: Zend\Validator\Date – předpokládali byste, že Date je validátor, nikoliv datum?
nevhodné: Zend\Controller\Request\Http – předpokládali byste, že Http je požadavek?

Proto krom specializace tříd je vhodné v názvu ponechat i obecnost:

lepší: Nette\Application\Responses\DownloadResponse
lepší: Zend\Validator\DateValidator
lepší: Zend\Controller\Request\HttpRequest

Ideální je, pokud existuje jednoslovný a přitom výstižný název. Ten lze vymyslet hlavně u tříd, které reprezentují něco z reálného světa:

nejlepší: Nette\Forms\Controls\Button – dvouslovné ButtonControl netřeba (avšak HiddenControl na Hidden zkrátit nelze)

2) jmenný prostor má mít výstižný název

Pochopitelně i samotný název jmenného prostoru musí být výstižný a výhodou je název kratší, bez zbytečností. Takovou zbytečností se mi zdá např. Component v Symfony\Component\Routing, protože bez něj by název nijak neutrpěl.

V některých situacích je třeba se rozhodnout mezi jednotným a množným číslem (Zend\Validator vs Zend\Validators), což je podobně nerozhodný problém, jako při volbě jednotných a množných čísel u databázových tabulek.

3) rozlište jmenné prostory a třídy

Pojmenovat třídu stejně jako jmenný prostor (tj. mít třídy Nette\Application a Nette\Application\Request) je technicky možné, mohlo by to však programátory mást a lépe se bude tomu vyhnout. Myslete i na to, jak dobře se bude výsledný kód číst nebo jak budete API někomu vysvětlovat.

4) omezte zbytečné duplicity (+ parciální namespace)

Ideální je, pokud název třídy a název prostoru neobsahují duplicitně stejnou informaci.

místo Nette\Http\HttpRequest raději Nette\Http\Request
místo Symfony\Component\Security\Authentication\AuthenticationTrustResolver raději třídu TrustResolver

Třída Nette\Http\Request neodporuje pravidlu č. 1 o výstižném názvu třídy i bez uvedení jmenného prostoru, naopak nám dovoluje elegantně využít parciální namespace:

use Nette\Http; // alias pro namespace

// dostupné jsou všechny třídy via Http:
$request = new Http\Request;
$response = new Http\Response;
// a navíc Http\Response je srozumitelnější než samotné Response

Pokud jmenné prostory chápeme jako balíčky, což je obvyklé, vede to k nešťastnému duplikování posledního slova:

Zend\Form\Form
Symfony\Component\Finder\Finder
Nette\Application\Application

Jmenné prostory také doslova svádí sdružovat třídy (např. různé implementace téhož rozhraní apod.) do vlastních prostorů, což opět vytváří duplicity:

Nette\Caching\Storages\FileStorage – tj. všechny úložiště v samostatném prostoru Storages
Zend\Form\Exception\BadMethodCallException – všechny výjimky do Exception
Symfony\Component\Validator\Exception – opět všechny výjimky do Exception

Sdružující namespaces prodlužují název a vytváří v něm duplicity, protože obecnost často není možné z názvu tříd odstranit (1. pravidlo). Jejich výhodou může být lepší orientace ve vygenerované API dokumentaci (téhož by však šlo dosáhnout i jinak) a snazší dostupnost při použití plnohodnotných IDE s napovídáním. Každopádně je doporučuji používat jen s rozvahou. Například pro vyčlenění výjimek se moc nehodí.

5) nezaměnitelnost tříd z více prostorů

Dle bodu 1) má mít třída výstižný název, což ale neznamená, že má být i jednoznačný v rámci celé aplikace. Obvykle stačí, aby byl jednoznačný v rámci jmenného prostoru. Pokud se však v kódu často používají vedle sebe dvě třídy z různých prostorů, nebo pokud mají mezi sebou jinou podstatnou souvislost, neměly by mít stejný název. Jinými slovy, nemělo by být nutné používat AS v klauzuli USE.

6) jednosměrné závislosti

Zvažte, jaké závislosti mají mezi sebou mít třídy z jednotlivých jmenných prostorů. Snažím se dodržovat:

pokud má třída ze jmenného prostoru A\B závislost na třídě ze jmenného prostoru A\C, neměla by žádná třída z A\C mít závislost na A\B
třídy ze jmenného prostoru A\B by neměly mít závislost na třídě z prostoru A\B\C (tohle berte s rezervou)

p.s.: neberte prosím tento článek jako dogma, jde jen o zachycení aktuálních myšlenek

19. 4. 2011 PHP Komentáře: 7

Vytváření elementů v jQuery

S pomocí jQuery lze vytvořit HTML element docela jednoduše:

var $el = $('<a href="http://phpfashion.com">blogísek</a>');

Do proměnné $el se přiřadí objekt jQuery obalující vytvořený HTML element (proto jsem použil dolar v názvu proměnné), k nativnímu DOM objektu se dostanete přes $el[0].

Co ale v případě, že potřebujeme jako hodnoty použít proměnné? Přímočaré řešení by vypadalo takto:

// špatně: riziko XSS
var url = 'http://phpfashion.com';
var title = 'blogísek';
var $el = $('<a href="' + url + '">' + title + '</a>');

Jenže, jak uvádí komentář v kódu, koledujeme si tímto o průšvih jménem Cross-site scripting (XSS). Stačí, aby například proměnná url obsahovala uvozovky a výsledek bude nezamýšlený. Proto je nutné proměnné escapovat, tj. nahradit znaky mající speciální význam za HTML entity. Na to si můžeme napsat funkci escapeHtml:

// správné, ale ne příliš přehledné
var escapeHtml = function(s) {
    return s.replace('&', '&amp;').replace('"', '&quot;')
        .replace("'", '&#039;').replace('<', '&lt;');
};

var $el = $('<a href="' + escapeHtml(url) + '">' + escapeHtml(title) + '</a>');

Skládání řetězců postrádá onu lehkost a srozumitelnost první ukázky, nemluvě o riziku, že escapeHtml zapomeneme zavolat. Naštěstí jQuery od verze 1.4 nabízí elegantní řešení: proměnné uvedeme ve druhém parametru (viz dokumentace)

// dokonalé
var $el = $('<a>', {
    href: url,
    text: title
});

Příjemné je, že takto lze kromě HTML atributů definovat i kaskádové styly a události:

// <a style="color: red;" onclick="..." href="http://phpfashion.com">blogísek</a>
var $el = $('<a>', {
    href: url,
    text: title,
    click: function(e) {
        alert(this.href);
    },
    css: {
        color: 'red'
    }
});

Dokonce dovnitř můžeme vložit další element:

// <a href="http://phpfashion.com"><img alt="Logo" src="images/logo.gif"></a>
var $el = $('<a>', {
    href: url,
    html: $('<img>', {
        src: 'images/logo.gif',
        alt: 'Logo'
    })
});

Fajnové, že?

p.s. pokud se chcete o jQuery dozvědět víc, přijďte na školení jQuery a AJAX.

24. 1. 2011 JavaScript Komentáře: 6

Školení jQuery a AJAX startuje!

„Ty bys měl školit Nette,“ řekl mi Vašek WebExpo Stoupa a já se pak přes půl roku rozhoupával, než v listopadu 2008 uskutečnil první školení Vývoj webových aplikací v Nette Framework. Od té doby prošlo kurzem asi 300 kolegů programátorů.

„Ty bys měl školit jQuery,“ řeklo mi pár účastníků školení Nette a já se pak přes půl roku rozhoupával, než vypsal první školení jQuery a AJAX, na které vás tímto zvu. (Než jsem se rozhoupal k napsání tohoto článku, kurz je z poloviny naplněn. Málo houpu.)

Co vám kurz dá? Vím, že to zní jako otřepaná fráze, ale rád bych ukázal, že oživování webové stránky pomocí JavaScriptu může být skutečně zábavné. Seznámím vás s nejpopulárnějším JavaScriptovým frameworkem jQuery na praktických příkladech. Přitom budeme dbát na čistý návrh a znovupoužitelnost, protože ve chvíli, kdy programátor zabředne do bastlení, je se zábavou smyčec. Nebo šmitec. Celým kurzem se potáhne ústřední motiv user experience, tj. vysvětlíme si a ukážeme, kterou cestou se vydat, aby výsledek byl pro uživatele co nejintuitivnější. Protože o nic jiného vlastně nejde.

Bylo by fajn, kdybyste na školení vyrazili se základní znalostí JavaScriptu (stačí rozumět tomuto článku bez kapitol Properties a Dědičnost). Pokud zatím neznáte jQuery a rádi byste to napravili, jsem vám k službám!

13. 1. 2011 JavaScript Komentáře: 5

Recenze knihy 1001 tipů a triků pro PHP

Když jsem se dozvěděl, že Jakub Vrána píše knížku 1001 tipů a triků o PHP, samozřejmě mě napadlo pár trapných fórků („1001 vtipů o PHP“, „to jich bude devět?“ nebo „č. 1: znáte Ruby?“) ale pak jsem si uvědomil, jak je to vlastně šíleně velké číslo. Schválně, zkuste vymyslet a napsat padesátku. Dáte to? Já leda s odřenýma játrama. No a pak další. A další. A další! Uff. Když pak Jakub hlásil, že se blíží do třetiny, vzpomněl jsem si na Marvinovo „Nejhorší bylo těch prvních deset miliónů.“

Humor mi došel ve chvíli, kdy mě Jakub požádal, jestli bych mu udělal korekturu. Co si budeme povídat, když váš kamarád napíše knihu, tak ji od něj dostanete, někam ji důmyslně založíte a až se setkáte, tak mu řeknete, že jste ji samozřejmě četli a jako že to fakt bylo dobrý a poplácáte ho po rameni nebo tam někde. Alespoň tak velí bonton. Ovšem když máte dělat korekturu, ocitáte se vstříc hrozbě, že ji doopravdy budete muset přečíst! Že bych mu ji po týdnu vrátil netknutou a bez jediného škrtu („čéče, sem to fakt čet a žádnou vyloženě jako chybu sem tam nenašel…“), o tom jsem vůbec neuvažoval, by mi to nezbaštil. Pustil jsem se do čtení a zjistil, že to je hodně dobrý materiál.

Byť školy nemám a z odborné literatury jsem přečetl jen Pixyho, Kruga a Koska, cítím se v PHP poměrně zdatný. Co mi může kniha od Jakuba dát? Ejhle, může. Jakub totiž na vydavatele ušil pěknou kulišárnu, ta kniha je o PHP spíš mimochodem. Je to prostě hromada zajímavých tipů a nápadů pro všechny, kdo se zabývají webovými aplikacemi. Navíc originálních tipů, nejde totiž o tištěnou verzi Jakubova blogu. V žádném případě nečekejte referenční příručku PHP nebo nudnou přehlídku funkcí, kdepak. Najdete tu tipy počínaje návodem, jak skrýt emailovou adresu před roboty, přes generování sitemap až po pádné argumenty, zda mít doménu s www. nebo bez.

U toho bych se zastavil. Ač s Jakubem máme na mnohé věci odlišné názory, s ním je radost nesouhlasit. On má totiž svůj postoj vždycky podpořený jasnou argumentací. U něj neexistuje „to se dělá tak, protože to tak dělá každý“ nebo „protože tak to dělá Nielsen|Zeldman|Lerdorf|Torvalds|(doplň si svou kapacitu)“, ale protože nad tím přemýšlel a došel k nějakému závěru. A to se jako červená niť táhne celou knihou. Takže ačkoliv bych mohl s něčím nesouhlasit, stěží bych v ní hledal chybu. Takovou preciznost jsem zažil snad jen u knih Douglase Crockforda.

Ale ať jen nechválím – kniha je sbírkou nápadů, které jsou sice tematicky uspořádané, ale chybí mi tam průvodní slovo, co by z toho dělalo souvislé čtivo. Chybí mi tam Miloš Frýba. A na můj vkus obsahuje příliš málo humoru a nadsázky

Každopádně knihu vřele doporučuji každému PHPčkaři, své si v ní najdou jak začátečníci, tak matadoři. Za cenu jednoho bifteku není nad čím váhat. A neříkám to proto, že je v ní zmíněné Nette V knihkupectvích by měla být od pondělí, nicméně dokud Jakub nabízí možnost nechat si ji za stejnou cenu poslat s jeho podpisem, tak knihkupectví nemají šanci.

8. 1. 2011 PHP Komentáře: 7