4. díl - Standardy jazyka PHP - PSR-3 a specifikace loggeru

PHP Standardy Standardy jazyka PHP - PSR-3 a specifikace loggeru

ONEbit hosting Unicorn College Tento obsah je dostupný zdarma v rámci projektu IT lidem. Vydávání, hosting a aktualizace umožňují jeho sponzoři.

V minulém dílu našeho seriálu o standardech jazyka PHP jsme dokončili specifikaci PSR-2, která se týkala stylu psaní kódu. Dnes se podíváme na PSR-3, která se točí okolo logování, což je zápis informací o běhu aplikace do souboru. Asi každý projekt včetně ITnetworku používá nějakou logovací třídu, která se hodí zejména při debugování nebo pro záznam neobvyklých situací, abychom jim mohli předcházet.

PSR-3 - Logovací rozhraní

Hlavním cílem rozhraní, které popisuje PSR-3, je umožnit knihovnám pracovat s objektem Psr\Log\Logge­rInterface a zapisovat tak logy jednoduchým a univerzálním způsobem. Frameworky a CMS systémy se speciálními požadavky MOHOU rozhraní rozšířit pro své účely, ale MĚLY by zachovat kompatibilitu s tímto dokumentem. Standard zajistí, že knihovny třetích stran, které aplikace používá, budou zapisovat do centralizovaného aplikačního logu.

Cíl je tedy zřejmý, zavedeme jeden log, který budou používat všechny součásti aplikace, což bude jistě pohodlnější a přehlednější.

Slovo "implementátor" v tomto dokumentu označuje někoho, kdo implementuje rozhraní "LoggerInterface" v logovací knihovně nebo frameworku. Na jednotlivé uživatele loggerů se odkazujeme jako na "uživatele".

Specifikace

Základy

Rozhraní LoggerInterface vystavuje 8 metod pro zápis logů 8 úrovní (podle RFC 5424). Jedná se o úrovně: debug, info, notice, warning, error, critical, alert a emergency. Jakým chybám by měly jednotlivé úrovně odpovídat je popsáno níže v komentářích u zdrojového kódu rozhraní.

Devátá metoda, log(), přijímá úroveň logu jako první argument. Volání této metody s jednou logovací úrovní MUSÍ mít stejný výsledek jako volání specifické metody pro tuto úroveň. Volání této metody bez definované úrovně MUSÍ vyvolat Psr\Log\Invali­dArgumentExcep­tion pokud implementace úroveň nezná. Uživatelé by NEMĚLI používat vlastní logovací úroveň, aniž by si byli jistí, že ji současná implementace podporuje.

Zpráva

Každá metoda přijímá jako zprávu řetězec nebo objekt s metodou __toString(). Implementátor MŮŽE mít speciální zpracování pro předávané objekty. V opačném případě MUSÍ objekty přetypovat na řetězec. Zpráva MŮŽE obsahovat zástupné identifikátory (placeholders), které implementátoři nahradí hodnotami z kontextového pole.

Názvy zástupných identifikátorů MUSÍ korespondovat s klíči v kontextovém poli.

Názvy zástupných identifikátorů MUSÍ být odděleny levou složenou závorkou { a pravou složenou závorkou }. Mezi identifikátory a oddělovači NESMÍ být žádné bílé znaky.

Názvy zástupných identifikátorů by MĚLY být složené jen ze znaků A-Z, a-z, 0-9, podtržítko _ a tečka .. Použití dalších znaků je vyhrazeno pro budoucí modifikace specifikace identifikátorů.

Implementátoři MOHOU používat zástupné identifikátory pro implementaci různých escapovacích strategií a pro překlad logů pro výpis. Uživatelé by zástupné znaky NEMĚLI předescapovávat, protože nemohou vědět v jakém kontextu se data zobrazí.

Následuje ukázková implementace nahrazení zástupných identifikátorů, která slouží pouze jako pří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á metoda přijímá pole jako kontextová data. Je to za účelem udržování dalších informací z vnějšku, které by bylo komplikované ukládat do řetězce. Toto pole může obsahovat cokoli. Implementátoři MUSÍ zajistit, aby s kontextovými daty nakládali co možná nejshovívavěji. Daná hodnota v kontextu NESMÍ vyvolat výjimku nebo jakýkoli PHP error, warning nebo notice.

Pokud se v kontextovém poli předává objekt Exception, MUSÍ být v klíči 'exception'. Logování výjimek je obvyklé a tímto umožňujeme implementátorům extrahovat stack trace z výjimky, pokud to logovací backend podporuje. Implementátoři stále MUSÍ ověřit, že je klíč 'exception' výjimka než ji tak použijí, protože MŮŽE obsahovat cokoli.

Třída Helper a rozhraní

Třída Psr\Log\Abstrac­tLogger vám poděděním umožní implementovat LoggerInterface a to implementováním generické metody log(). Dalších 8 metod do ni předává zprávu a kontext.

Podobně k použití Psr\Log\LoggerTrait stačí implementovat pouze generickou metodu log(). Nezapomeňte, že jelikož traity neumí implementovat rozhraní, je v tomto případě nutné implementovat LoggerInterface.

Psr\Log\NullLogger je poskytován spolu s rozhraním. MŮŽE být použit ostatními uživateli k propadnutí do implementace "černé díry" (logger se tváří že funguje, ale nikam se neukládá), když jim není předán žádný logger. Nicméně pokud je vytvoření datového kontextu náročné, může být podmíněné logování lepším přístupem.

Rozhraní Psr\Log\Logge­rAwareInterfa­ce obsahuje pouze metodu setLogger(Log­gerInterface $logger) a může být použito frameworky k auto-wiringu libovolných instancí s loggerem.

Trait Psr\Log\Logge­rAwareTrait může být jednoduše použit k implementaci ekvivalentního rozhraní v libovolné třídě. Poskytuje přístup k $this->logger.

Třída Psr\Log\LogLevel sdružuje konstanty pro 8 logovacích úrovní.

Příště si uvedeme zdrojové kódy zmíněného rozhraní s českými komentáři a následně si tato rozhraní zkusíme implementovat a vytvořit vlastní standardní logger.


 

  Aktivity (1)

Článek pro vás napsal David Čápka
Avatar
Autor pracuje jako softwarový architekt a pedagog na projektu ITnetwork.cz (a jeho zahraničních verzích). Velmi si váží svobody podnikání v naší zemi a věří, že když se člověk neštítí práce, tak dokáže úplně cokoli.
Unicorn College Autor se informační technologie naučil na Unicorn College - prestižní soukromé vysoké škole IT a ekonomie.

Jak se ti líbí článek?
Celkem (2 hlasů) :
4.54.54.54.54.5


 


Miniatura
Všechny články v sekci
Standardy jazyka PHP

 

 

Komentáře

Děláme co je v našich silách, aby byly zdejší diskuze co nejkvalitnější. Proto do nich také mohou přispívat pouze registrovaní členové. Pro zapojení do diskuze se přihlas. Pokud ještě nemáš účet, zaregistruj se, je to zdarma.

Zatím nikdo nevložil komentář - buď první!