Logger - Jet\Logger

Logger is a simple unified interface and container, which on the one hand allows to unify the way of recording events in the application and on the other hand to modify completely and freely how and where the events will be stored.

On the one hand, there is a set of simple static methods used by the application. On the other end is the so-called logger, which takes care of saving the event (to the database, to files, to the system log, etc., or even discarding the event record).

The logger itself is not part of Jet, but it is part of the application space. It is up to you how you implement it.

Initialization

A logger is just an empty container that needs to be "populated" and thus passed to the backend, which will actually do the logging - i.e., storing the logs (arbitrarily how and arbitrarily where). A logger is a class (or classes) in your application space that implements the Jet\Logger_Interface interface. So you are in full control of how you store the logs. The sample application includes an example implementation of the logger, of course, and you can use it or modify it as you wish.

As with authentication and authorization, it is more than useful to have different logging for different situations. Thus, if you use Jet MVC, you can (and should) have different loggers for different bases. It is possible and advisable to initialize a logger in the base initializer, for example. Let's see an example:

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() );
        
        //... ... ...
    }
    
}

Usage

Every event has some class, or in other words, kind. It can be information about a successful operation, general information, a warning, a dangerous event, information about a failure, but anything else (nothing prevents you from defining additional classes/types). The main purpose is to distinguish the type and severity of the event and make a basic classification. What is it good for? For example, the log can be read by monitoring, which can respond to severe events and so on. Apart from simply being correct to distinguish the trivial notification that user X has successfully logged in from the fact that user Y has unsuccessfully tried to log in for the hundredth time (and therefore perhaps something nefarious is going on), other functionality and logic can be implemented based on this classification.

Also, each event must have some completely unique identifier - a text constant. Such an identifier so that it is possible to trace the type of event (for example, all failed login attempts, etc.) in the log at once.

And it is also important that the event has some brief but clear and user-readable description. For example: 'User XY has logged in', or 'Article XY has been edited', etc.

Last but not least, an event may (or may not) have information about the context to which it refers. For example, if it is about modifying an item in an e-shop, the event may have the ID of the object, then the user-readable name, and last but not least context data - that is, any data relevant to the event.

Let's take a trivial application. We want to record as information that so-and-so user has just logged out:

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()
);

Or, as an example, let's take a successful edit of a product in the e-shop administration:

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
);

Or the mentioned logging of failed logins can be implemented as follows:

Logger::warning(
    event: Auth_Controller_Admin::EVENT_LOGIN_FAILED,
    event_message: 'Login failed. Username: \'' . $username . '\'',
    context_object_id: $username,
);

Predefined classes / event types

Constanta Value Meaning of
Logger::EVENT_CLASS_SUCCESS'success'Information about a successful operation.
Logger::EVENT_CLASS_INFO'info'General information.
Logger::EVENT_CLASS_WARNING'warning'Warning.
Logger::EVENT_CLASS_DANGER'danger'Dangerous event.
Logger::EVENT_CLASS_FAULT'fault'Failure.

Overview of Jet\Logger class methods

Method Meaning of
public static setLogger(
Logger_Interface $logger
): void 		Sets the logger instance.
public static setLoggerProvider(
callable $provider
): void 		It allows lazy loading. Instead of creating and setting the logger instance, it is possible to set a factory function that creates the logger instance only when the application needs to use the logger for the first time.
public static getLogger(
): Logger_Interface|null 		Returns the current instance of the logger.
public static common(
string $event_class,
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Logging events of any class/type. Actually calls the logger.
If the logger instance is not set, then it does not perform logging.

Parameters:
  • $event_class
    Class/type of event.
  • $event
    Event identifier. It should be a text constant that uniquely identifies the event.
  • $event_message
    Text description of the event - readable for the user. Can/should include event details (e.g. 'User XXXX (id:123) has logged out')
  • $context_object_id
    The ID of the object to which the event relates. For example, if the event is editing an article, this parameter should have the value of the ID of the edited article.
  • $context_object_name
    The user-readable name of the object to which the event applies. For example, when editing an article, this parameter can have the value of the article title and so on.
  • $context_object_data
    Arbitrary event context data. As an example, let's take again the editing of an article. It can be an instance of the article and the log will record its form after editing. For example, it can also create an edit history and so on.
public static success(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Logging of class/type event Logger::EVENT_CLASS_SUCCESS

Functionally identical to the common method.
public static info(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Logging of class/type event Logger::EVENT_CLASS_INFO

Functionally identical to the common method.
public static warning(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Logging of class/type event Logger::EVENT_CLASS_WARNING

Functionally identical to the common method.
public static danger(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Logging of class/type event Logger::EVENT_CLASS_DANGER

Functionally identical to the common method.
public static fault(
string $event,
string $event_message,
string $context_object_id = '',
string $context_object_name = '',
mixed $context_object_data = []
) 		Logging of class/type event Logger::EVENT_CLASS_FAULT

Functionally identical to the common method.

Classes in the sample application

Loggery

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

Events

  • JetApplication\Logger_Event
    A generic abstract class representing an event stored in a database built on DataModel.
  • JetApplication\Logger_Admin_Event
    It inherits from Logger_Event and specifies a specific database table name for storing administration events.
  • JetApplication\Logger_REST_Event
    Inherits from Logger_Event and specifies a specific database table name for storing REST API server events.
  • JetApplication\Logger_Web_Event
    It inherits from Logger_Event and specifies a specific database table name for storing site events.
Previous chapter
Session - Jet\Session
Next chapter
Jet\Logger_Interface
GitHub