4. diel - Štandardy jazyka PHP - PSR-3 a špecifikácie loggeru

V minulej lekcii, Štandardy jazyka PHP - PSR-2 časť druhá , sme dokončili špecifikáciu PSR-2, ktorá sa týkala štýlu písania kódu. Dnes sa pozrieme na PSR-3, ktorá sa točí okolo logovanie, čo je zápis informácií o behu aplikácie do súboru. Asi každý projekt vrátane ITnetworku používa nejakú logovacie triedu, ktorá sa hodí najmä pri debugovania alebo pre záznam neobvyklých situácií, aby sme im mohli predchádzať.

PSR-3 - Logovacie rozhranie

Hlavným cieľom rozhranie, ktoré opisuje PSR-3, je umožniť knižniciam pracovať s objektom Psr \ Log \ LoggerInterface a zapisovať tak logami jednoduchým a univerzálnym spôsobom. Frameworku a CMS systémy so špeciálnymi požiadavkami MÔŽU rozhranie rozšíriť pre svoje účely, ale MALI by zachovať kompatibilitu s týmto dokumentom. Štandard zabezpečí, že knižnice tretích strán, ktoré aplikácia používa, budú zapisovať do centralizovaného aplikačného logu.

Cieľ je teda zrejmý, zavedieme jeden log, ktorý budú používať všetky súčasti aplikácie, čo bude iste pohodlnejšie a prehľadnejšie.

Slovo "implementátor" v tomto dokumente označuje niekoho, kto implementuje rozhranie "LoggerInterface" v logovacie knižnici alebo frameworku. Na jednotlivých užívateľov loggerov sa odkazujeme ako na "užívateľa".

Špecifikácia

Základy

Rozhranie LoggerInterface vystavuje 8 metód pre zápis logov 8 úrovní (podľa RFC 5424). Jedná sa o úrovne: debug, info, notice, warning, error, critical, alert a emergency. Akým chybám by mali jednotlivé úrovne zodpovedať je popísané nižšie v komentároch u zdrojového kódu rozhrania.

Deviata metóda, log (), prijíma úroveň logu ako prvý argument. Volanie tejto metódy s jednou logovacie úrovňou MUSÍ mať rovnaký výsledok ako volanie špecifické metódy pre túto úroveň. Volanie tejto metódy bez definované úrovne MUSÍ vyvolať Psr \ Log \ InvalidArgumen­tException ak implementácie úroveň nepozná. Používatelia by NEMALI používať vlastné logovacie úroveň, bez toho aby si boli istí, že ju súčasná implementácia podporuje.

Správa

Každá metóda prijíma ako správu reťazec alebo objekt s metódou __toString (). Implementátor MÔŽE mať špeciálne spracovanie pre prenesené objekty. V opačnom prípade MUSÍ objekty pretypovať na reťazec. Správa MÔŽE obsahovať zástupné identifikátory (Placeholders), ktoré implementátori nahradia hodnotami z kontextového poľa.

Názvy zástupných identifikátorov MUSÍ korešpondovať s kľúčmi v kontextovom poli.

Názvy zástupných identifikátorov MUSÍ byť oddelené ľavú zloženú zátvorkou {a pravú zloženú zátvorkou}. Medzi identifikátory a oddeľovačmi NESMIE byť žiadne biele znaky.

Názvy zástupných identifikátorov by MALI byť zložené len zo znakov AZ, az, 0-9, podčiarkovník _ a bodka .. Použitie ďalších znakov je vyhradené pre budúce modifikácie špecifikácie identifikátorov.

Implementátori MÔŽU používať zástupné identifikátory pre implementáciu rôznych escapovacích stratégií a pre preklad logov pre výpis. Používatelia by zástupné znaky NEMALI předescapovávat, pretože nemôžu vedieť v akom kontexte sa dáta zobrazia.

Nasleduje ukážková implementácia nahradenie zástupných identifikátorov, ktorá slúži len ako príklad:

/**
* Interpoluje hodnoty z kontextového pole do zástupných identifikátorů ve zprávě
*/
function interpolate($message, array $context = array())
{
  // vytvoří nahrazovací pole se závorkami okolo kontextových klíčů
  $replace = array();
  foreach ($context as $key => $val) {
      $replace['{' . $key . '}'] = $val;
  }

  // interpoluje nahrazovací hodnoty do zprávy a vrátí je
  return strtr($message, $replace);
}

// zpráva se zástupným identifikátorem, ohraničeným v závorkách
$message = "User {username} created";

// kontextové pole s názvy zástupných identifikátorů => nahrazovacích hodnot
$context = array('username' => 'bolivar');

// vypíše "User bolivar created"
echo interpolate($message, $context);

Kontext

Každá metóda prijíma poľa ako kontextová dáta. Je to za účelom udržiavanie ďalších informácií zvonku, ktoré by bolo komplikované ukladať do reťazca. Toto pole môže obsahovať čokoľvek. Implementátori MUSÍ zabezpečiť, aby s kontextovými dátami nakladali čo možno nejshovívavěji. Daná hodnota v kontexte NESMIE vyvolať výnimku alebo akýkoľvek PHP error, warning alebo notice.

Ak sa v kontextovom poli odovzdáva objekt Exception, MUSÍ byť v kľúči 'exception'. Logovanie výnimiek je obvyklé a týmto umožňujeme implementátorom extrahovať stack trace z výnimky, ak to logovacie backend podporuje. Implementátori stále MUSÍ overiť, že je kľúč 'exception' výnimka než ju tak použijú, pretože MÔŽE obsahovať čokoľvek.

Trieda Helper a rozhrania

Trieda Psr \ Log \ AbstractLogger vám poděděním umožní implementovať LoggerInterface a to implementovaním generické metódy log (). Ďalších 8 metód do ňu odovzdáva správu a kontext.

Podobne na použitie Psr \ Log \ LoggerTrait stačí implementovať len generickú metódu log (). Nezabudnite, že keďže Trait nevie implementovať rozhranie, je v tomto prípade nutné implementovať LoggerInterface.

Psr \ Log \ NullLogger je poskytovaný spolu s rozhraním. MÔŽE byť použitý ostatnými užívateľmi k prepadnutiu do implementácie "čiernej diery" (logger sa tvári že funguje, ale nikam sa neukladá), keď im nie je odovzdaný žiadny logger. Avšak ak je vytvorenie dátového kontextu náročné, môže byť podmienené logovanie lepším prístupom.

Rozhranie Psr \ Log \ LoggerAwareIn­terface obsahuje len metódu setLogger (LoggerInterface $ logger) a môže byť použité frameworky k auto-Wiring ľubovoľných inštancií s loggerom.

Trait Psr \ Log \ LoggerAwareTrait môže byť jednoducho použitý na implementáciu ekvivalentného rozhrania v ľubovoľnej triede. Poskytuje prístup k $ this-> logger.

Trieda Psr \ Log \ LogLevel združuje konštanty pre 8 logovacích úrovní.

Nabudúce si v lekcii Štandardy jazyka PHP - Implementácia PSR-3 uvedieme zdrojové kódy spomínaného rozhrania s českými komentármi a následne si tieto rozhrania skúsime implementovať a vytvoriť vlastné štandardné logger.