The logging service is the only example of a service provided in the foundations module. That's because we believe that every plugin should use logging (hence also why every service is forced to implement the
In short, the logging service is a multi-handler service that accepts any handler implementing the
LoggingHandlerInterfaceinterface. It's expected to provide the service with two handlers, one with the ID framework and one with the ID plugin.
By default, the logging service attempts to log using the plugin handler, whereas messages logged by framework modules will always use the framework handler. In order to include sensitive data in the log messages, you need to instantiate the service with the second parameter set to
The logging service doesn't understand what data is of sensitive nature and which is not. It's your responsibility to mark it accordingly when composing the logged message.
If you want to disable logging for your plugin, it's enough to not register the two aforementioned handlers. The service will simply default to using the NullLogger.
The default logging handler requires an ID and a PSR-3 logger. We recommend using Monolog for your PSR-3 logger needs, but if you're building a WooCommerce plugin, please be aware that the WooCommerce module provides a handler compatible with the WooCommerce logger.
Here is a simple example for instantiating the logging service using Monolog loggers:
use Monolog\Handler\RotatingFileHandler as MonologRotatingFileHandler;
use Monolog\Logger as MonologLogger;
use function DeepWebSolutions\Framework\dws_wp_framework_get_temp_dir_path;
$min_log_level = Request::has_debug() ? MonologLogger::DEBUG : MonologLogger::ERROR;
$logs_path = dws_wp_framework_get_temp_dir_path() . 'my-test-plugin' . DIRECTORY_SEPARATOR;
$monolog_handler = new MonologRotatingFileHandler( $logs_path . 'errors.log', 30, $min_log_level );
$dws_handlers = array(
new LoggingHandler( 'framework', new MonologLogger( 'framework', array( $monolog_handler ) ) ),
new LoggingHandler( 'plugin', new MonologLogger( 'plugin', array( $monolog_handler ) ) ),
$plugin_instance = dws_test_plugin_instance();
$dws_logging_service = new LoggingService( $plugin_instance, $dws_handlers, Request::has_debug() );
The logging service provides two public methods:
log_event-- returns an instance of the
LogMessageBuilderclass which can be further configured to perform other actions before logging the message.
log_event_and_finalize-- shortcut for calling the
log_eventmethod and finalizing the message.
Instances of the
LogMessageBuilderclass need to have the finalize method called on them for the message to be logged and the other actions performed as well.
If you don't call
LogMessageBuilderobjects, the message will never be logged!
A few things that the message builder can do:
- If the service is configured to ignore sensitive content, it removes all the text wrapped in
- By default, it returns
finalize, but it can be configured to return the logged message wrapped in an exception or a given throwable object.
And here are examples on how to use the message builder (we'll assume the logging service instantiated above is present in this context as well):
// The following two lines are EQUIVALENT.
$dws_logging_service->log_event( 'Error happened' )
->set_log_level( LogLevel::DEBUG )
$dws_logging_service->log_event_and_finalize( 'Error happened' );
// This message will be logged with WP too.
$dws_logging_service->log_event( 'Error happened in function' )
->doing_it_wrong( 'my_awesome_func', '1.3.5' )
// This message will return an exception.
$exception = $dws_logging_service->log_event_and_finalize( 'Property A not found' )
->return_exception( NotFoundException::class )
echo get_class( $exception ); // echoes 'NotFoundException'
echo $exception->getMessage(); // echoes 'Property A not found'