Logger - Jet\Logger

Logger je jednoduché unifikované rozhraní a kontejner, který na jedné straně umožňuje v aplikaci unifikovat způsob záznamu událostí a na druhé straně zcela a libovolně modifikovat jak a kam budou události ukládány.

Tedy na jedné straně je sada jednoduchých statických metod, které používá aplikace. Na druhém konci je tzv. logger, který se postará o uložení události (do databáze, do souborů, systémového logu a podobně, nebo i zahození záznamu o dané události).

Samotný logger není součástí Jet, ale je součástí aplikačního prostoru. Je tedy na vás jak jej implementujete.

Inicializace

Logger je pouze prázdný kontejner, který je nutné "naplnit" a tedy předat backend, který bude prakticky provádět logování - tedy ukládání záznamů (libovolně jak a libovolně kam). Logger je třída (či třídy) ve vašem aplikačním prostoru implementující rozhraní Jet\Logger_Interface. To jak budete záznamy ukládat máte tedy plně pod kontrolou. Součástí ukázkové aplikace příklad implementace loggeru samozřejmě najdete a pokud chcete, můžete jej použít, či libovolně modifikovat.

Obdobně jako u autentizace a autorizace je i u loggeru více jak vhodné mít různé logování pro různé situace. Tedy pokud budete používat Jet MVC, tak můžete (a měli byste) mít různé loggery pro různé báze. Je možné a vhodné inicializovat logger například v inicializátoru báze. Ukažme si příklad: namespace JetApplication;

//... ... ...
use Jet\Logger;
use Jet\MVC_Router;
//... ... ...

class Application_Admin
{
    public static function init( MVC_Router $router ): void
    {
        Logger::setLogger( new Logger_Admin() );
        
        //... ... ...
    }
    
}

Použití

Každá událost má nějakou třídu, nebo jinak řečeno druh. Může jít o informaci o úspěšně provedné operaci, obecnou informaci, varování, nebezpečnou událost, informaci o selhání, ale cokoliv dalšího (nic vám nebrání si další třídy / druhy definovat). Hlavním smyslem je rozlišit druh a závažnost události a provést základní klasifikaci. K čemu je to dobré? Log může číst například monitoring, který může reagovat na závažné události a podobně. Krom toho že je prostě správné rozlišit triviální oznámení o tom, že se uživatel X úspěšně přihlásil od skutečnosti, že uživatel Y se již po sté pokusil přihlásit neúspěšně (a možná se tedy jedná o něco nekalého) je možné na základě této klasifikace realizovat i další funkčnost a logiku.

Dále každá událost musí mít nějaký zcela jednoznačný identifikátor - textovou konstantu. Takový identifikátor, aby bylo možné naráz v logu dohledat daný druh události (například všechny neúspěšné pokusy o přihlášení a podobně).

A dále je důležité, aby událost měla nějaký stručný, ale jasný a pro uživatele čitelný popis. Například: 'Uživatel XY se přihlásil', nebo 'Článek XY byl upraven' a podobně.

V neposlední řadě událost může (ale nemusí) mít informace o kontextu, kterého se týká. Například pokud by se jednalo o úpravu zboží v e-shopu, tak událost může u sebe mít ID daného objektu, dále pro uživatele čitelný název a v neposlední řadě kontextová data - tedy libovolná data pro danou událost důležitá.

Ukažme si triviální použití. Chceme jako informaci zaznamenat, že se ten a ten uživatel právě právě odhlásil: Logger::info(
    event: Auth_Controller_Admin::EVENT_LOGOUT,
    event_message: 'User ' . $user->getUsername() . ' (id:' . $user->getId() . ') logged out',
    context_object_id: $user->getId(),
    context_object_name: $user->getName()
);

Nebo si jako příklad vezměme úspěšnou úpravu produktu v administraci e-shopu: Logger::success(
    event: Product::EVENT_EDIT,
    event_message: 'Product ' . $product->getTitle() . ' (id:' . $product->getId() . ') has been updated',
    context_object_id: $product->getId(),
    context_object_name: $product->getTitle(),
    context_object_data: $product
);

Nebo ono zmiňované logování neúspěšného přihlášení lze realizovat takto: Logger::warning(
    event: Auth_Controller_Admin::EVENT_LOGIN_FAILED,
    event_message: 'Login failed. Username: \'' . $username . '\'',
    context_object_id: $username,
);

Předdefinované třídy / druhy událostí

Konstanta Hodnota Význam
Logger::EVENT_CLASS_SUCCESS'success'Informace o úspěšně provedné operaci.
Logger::EVENT_CLASS_INFO'info'Obecná informace.
Logger::EVENT_CLASS_WARNING'warning'Varování.
Logger::EVENT_CLASS_DANGER'danger'Nebezpečná událost.
Logger::EVENT_CLASS_FAULT'fault'Selhání.

Přehled metod třídy Jet\Logger

Metoda Význam
public static setLogger(
Logger_Interface $logger
): void 		Nastaví instanci loggeru.
public static setLoggerProvider(
callable $provider
): void 		Umožňuje tzv. lazy loading. Místo vytvoření a nastavení instance loggeru je možné nastavit tovární funkci, která vytvoří instanci loggeru až v momentě, kdy aplikace potřebuje logger poprvé použít.
public static getLogger(
): Logger_Interface|null 		Vrátí aktuální instanci loggeru.
public static common(
string $event_class,
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Zalogování události libovolné třídy / druhu. Ve skutečnosti volá logger.
Pokud instance loggeru není nastavena, pak logování neprovádí.

Parametry:
  • $event_class
    Třída / druh události.
  • $event
    Identifikátor události. Má se jednat o textovou konstantu, která jednoznačně identifikuje danou událost.
  • $event_message
    Textový popis události - čitelný pro uživatele. Může / má obsahovat i podrobnosti o události (např: 'Uživatel XXXX (id:123) se odhlásil')
  • $context_object_id
    ID objektu, kterého se událost týká. Tedy například pokud je událost úprava článku, tak tento parametr by měl mít hodnotu ID editovaného článku.
  • $context_object_name
    Uživatelem čitelný název objektu, kterého se událost týká. Například při editaci článku může mít tento parametr hodnotu titulku článku a podobně.
  • $context_object_data
    Libovolná kontextová data události. Jako příklad si opět vezměme editaci článku. Může to být klidně instance daného článku a do logu se tedy zaznamená jeho podoba po úpravě. Může tak například vzniknout i historie úprav a podobně.
public static success(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Zalogování události třídy / druhu Logger::EVENT_CLASS_SUCCESS

Funkčně zcela shodné s metodou common.
public static info(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Zalogování události třídy / druhu Logger::EVENT_CLASS_INFO

Funkčně zcela shodné s metodou common.
public static warning(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Zalogování události třídy / druhu Logger::EVENT_CLASS_WARNING

Funkčně zcela shodné s metodou common.
public static danger(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Zalogování události třídy / druhu Logger::EVENT_CLASS_DANGER

Funkčně zcela shodné s metodou common.
public static fault(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Zalogování události třídy / druhu Logger::EVENT_CLASS_FAULT

Funkčně zcela shodné s metodou common.

Třídy v ukázkové aplikaci

Loggery

  • JetApplication\Logger_Admin
  • JetApplication\Logger_REST
  • JetApplication\Logger_Web

Události

  • JetApplication\Logger_Event
    Obecná abstraktní třída představující událost ukládanou do databáze postavená na DataModel.
  • JetApplication\Logger_Admin_Event
    Dědí od Logger_Event a určuje konkrétní název databázové tabulky pro uložení událostí administrace.
  • JetApplication\Logger_REST_Event
    Dědí od Logger_Event a určuje konkrétní název databázové tabulky pro uložení událostí REST API serveru.
  • JetApplication\Logger_Web_Event
    Dědí od Logger_Event a určuje konkrétní název databázové tabulky pro uložení událostí webu.
Předchozí kapitola
Session - Jet\Session
Další kapitola
Jet\Logger_Interface
GitHub