DWS WP Framework
  • Welcome
  • Primary goals
    • Modular design
    • No 3rd-party dependencies
  • Key concepts and dev tools
    • PHP and WP requirements
    • Object-Oriented Programming
    • Semantic Versioning
    • Version Control (git / GitHub)
    • Dependency Management (Composer)
    • Automated Testing (Codeception + Github Actions)
    • Dependency Injection (PHP-DI)
    • Coding Standards (PHPCS and PHPMD)
    • Dependencies Scoping (PHP-Scoper)
    • TypeScript and Sass
    • Task Runners (Grunt)
  • Setting up your dev environment
    • Windows
  • Your first plugin
    • Multiple plugins using the framework on the same site
  • Frequently Asked Questions
  • Bootstrapper Module
    • Motivation
    • How it works
    • How to use
    • White Labeling
  • Helpers Module
    • Motivation
    • How to use
  • Foundations Module
    • Motivation and How to use
    • Actions
      • Local action traits
      • Extension action traits
      • Integration action traits
    • States
    • Utilities
      • Stores
      • Handlers and Services
        • Logging Service
  • Plugin
    • Main Plugin Instance
    • Plugin Components
  • Hierarchies
  • Helpers
  • Utilities Module
    • Motivation and How to use
    • Hooks Service
      • Scoped Handler
    • Shortcodes Service
    • Templating Service
    • Assets Service
      • Scripts Handler
      • Styles Handler
    • CRON Events Service
      • Action Scheduler Handler
    • Admin Notices Service
    • Dependencies Service
    • Validation Service
  • Core Module
    • Motivation and How to use
    • Plugin Tree
      • Plugin Root
      • Plugin Functionality
    • Plugin Components
      • Internationalization
      • Installation / Upgrade / Uninstallation
  • Settings Module
    • Motivation and How to use
    • Settings Service
      • WordPress Handler
      • MetaBox Handler
      • ACF Handler
    • Validated Settings
  • WooCommerce Module
    • Motivation and How to use
    • Extended WC Logger
    • WC Settings Handler
Powered by GitBook
On this page

Was this helpful?

  1. Foundations Module
  2. Utilities
  3. Handlers and Services

Logging Service

PreviousHandlers and ServicesNextPlugin

Last updated 4 years ago

Was this helpful?

The 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 interface).

In short, the logging service is a multi-handler service that accepts any handler implementing the interface. 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 true.

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 .

The requires an ID and a logger. We recommend using for your PSR-3 logger needs, but if you're building a WooCommerce plugin, please be aware that the provides a handler compatible with the WooCommerce logger.

Here is a simple example for instantiating the logging service using Monolog loggers:

<?php

namespace DeepWebSolutions\Plugins\MyTestPlugin;

use DeepWebSolutions\Framework\Foundations\Logging\LoggingHandler;
use DeepWebSolutions\Framework\Foundations\Logging\LoggingService;
use DeepWebSolutions\Framework\Helpers\WordPress\Request;

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_and_finalize -- shortcut for calling the log_event method and finalizing the message.

Instances of the LogMessageBuilder class 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 finalize on LogMessageBuilder objects, 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 <sensitive></sensitive> tags.

  • By default, it returns null when calling 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):

<?php

use DeepWebSolutions\Framework\Foundations\Exceptions\NotFoundException;
use Psr\Log\LogLevel;

// The following two lines are EQUIVALENT.
$dws_logging_service->log_event( 'Error happened' )
                ->set_log_level( LogLevel::DEBUG )
                ->finalize();

$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' )
                ->finalize();

// This message will return an exception.
$exception = $dws_logging_service->log_event_and_finalize( 'Property A not found' )
                ->return_exception( NotFoundException::class )
                ->finalize();
echo get_class( $exception ); // echoes 'NotFoundException'
echo $exception->getMessage(); // echoes 'Property A not found'

log_event -- returns an instance of the class which can be further configured to perform other actions before logging the message.

It can log the message using WordPress' as well.

logging service
LoggingServiceAwareInterface
LoggingHandlerInterface
NullLogger
default logging handler
PSR-3
Monolog
WooCommerce module
LogMessageBuilder
_doing_it_wrong