Vydělávej až 160.000 Kč měsíčně! Akreditované rekvalifikační kurzy s garancí práce od 0 Kč. Více informací.
Hledáme nové posily do ITnetwork týmu. Podívej se na volné pozice a přidej se do nejagilnější firmy na trhu - Více informací.

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

V minulé lekci, Standardy jazyka PHP - PSR-2 část druhá, 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 v lekci Standardy jazyka PHP - Implementace PSR-3 uvedeme zdrojové kódy rozhraní s českými komentáři a následně si rozhraní zkusíme implementovat a vytvořit vlastní standardní logger.


 

Předchozí článek
Standardy jazyka PHP - PSR-2 část druhá
Všechny články v sekci
Standardy jazyka PHP
Přeskočit článek
(nedoporučujeme)
Standardy jazyka PHP - Implementace PSR-3
Článek pro vás napsal David Hartinger
Avatar
Uživatelské hodnocení:
5 hlasů
David je zakladatelem ITnetwork a programování se profesionálně věnuje 15 let. Má rád Nirvanu, nemovitosti a svobodu podnikání.
Unicorn university David se informační technologie naučil na Unicorn University - prestižní soukromé vysoké škole IT a ekonomie.
Aktivity