Using Plop usually involves 3 steps, detailed below.
TL;DR: simply read the section on Loading Plop’s classes then skip all the way down to the section on Logging some messages.
The way to load Plop’s classes depends on the installation method selected:
For the PHAR installation method, add this snippet near the top of your main PHP file:
require_once('path/to/Plop-latest.phar');
(adjust the path with the name of the PHAR archive you downloaded)
For the Composer installation method, add this snippet instead near the top of your main PHP file:
require_once('path/to/vendor/autoload.php');
For an installation from sources,
require_once('src/Autoloader.php');
\Plop\Autoloader::register();
If you’re not interested in fine-tuning Plop, you may skip the rest of this page until you reach the part about Logging some messages.
There are 4 different types of objects that you can configure in Plop. Each one is described below.
A logger intercepts log messages for a given method, class, file or directory. This is decided at construction time based on the arguments passed to :api:`Plop::Logger::__construct`.
Internally, Plop builds up a hierarchy of loggers like so:
root-level logger
namespace-level logger
class-level logger
method/function-level logger
Log messages “bubble up”. That is, Plop first looks for a method or function-level logger to handle the message. If none can be found, it looks for a class-level logger (in case the message was emitted from a method). Then it looks for a namespace-level logger, then a logger for the parent’s namespace, etc. until it reaches the root-level logger, which always exists.
Whichever logger is found first will be the one to handle the message.
Note
The root-level logger) comes pre-configured with a handler that logs messages to STDERR using some very basic formatting.
Several aspects of a logger can be configured, such as:
Once a logger has been created and configured, you can tell Plop about it, using the following code snippet:
$logging = \Plop\Plop::getInstance();
$logging[] = $newlyCreatedLogger;
This will add the logger to the list of loggers already known to Plop. If a logger had already been registered in Plop with the same “identity” (ie. the same namespace, class and method names), it will automatically be replaced with the new one.
See also
Filters are associated with either loggers or handlers through an object implementing :api:`Plop::FiltersCollectionInterface` (usually an instance of :api:`Plop::FiltersCollection`) and are used to restrict which messages will be handled. They are applied once the message has been turned into a log record and work by defining various criteria such a record must respect.
If a record respects all of the criteria given in the collection, the handlers associated with the logger are called in turn to do their work.
Note
The “level” associated with a logger acts like a lightweight filter. In fact, the same effect could be obtained by defining a collection containing an instance of :api:`Plop::Filter::Level` with the level desired.
Warning
Not all handlers make use of filters. Therefore, depending on the handlers used, it is possible that the filters will be ignored entirely.
To associate a new filter with a logger or handler, use the following code snippet:
$filters = $logger_or_handler->getFilters();
$filters[] = $newFilter;
Please note that this will not replace existing filters. Records will still have to pass the previous filters, but they will also have to pass the new filter before they can be handled.
See also
Handlers are associated with loggers through an object implementing :api:`Plop::HandlersCollectionInterface` (usually an instance of :api:`Plop::HandlersCollection`) and are used to define the treatment applied to log records.
Various types of handlers exist that can be used to log message to different locations such as the system’s event logger (syslog), a (rotated) file, a network socket, ...
Like with loggers, several aspects of a handler can be configured:
To associate a new handler with a logger, use the following code snippet:
$handlers = $logger->getHandlers();
$handlers[] = $newHandler;
Please note that this will not replace existing handlers. Also, both the previously defined handlers and the newly added one will be called when a log record must be handled.
See also
Each handler has an associated formatter, which is used when a record needs formatting. A formatter defines how the final message will look like.
There are a few things about a formatter that you can configure:
The main format. This string serves as a pattern for the final message.
When using an instance of :api:`Plop::Formatter` with default settings as the formatter, it may contain Python-like string formats using the syntax for dictionaries.
That is, it may contain something like the following:
[%(asctime)s] %(levelname)s - %(message)s
The default format in that case is defined in :api:`Plop::Formatter::DEFAULT_FORMAT`.
Several pre-defined formats exist that depend on the particular implementation used to represent records. For example, :api:`Plop::Record` closely follows the formats defined by Python’s logging module whenever they are applicable.
The format for dates and times.
When using an instance of :api:`Plop::Formatter` as the formatter, it uses the formatting options from PHP’s date() function. Also, the default format for dates and times is then defined in :api:`Plop::Formatter::DEFAULT_DATE_FORMAT`.
The current timezone as a DateTimeZone object. This information is used when formatting dates and times for log records that were created in a timezone that does not match the local timezone.
To associate a new formatter with a handler, use the following code snippet:
$handler->setFormatter($newFormatter);
Please note that this will replace any formatter previously in place.
See also
Logging messages with Plop usually only involves the following sequence:
// First, grab an instance of Plop.
// Plop uses a singleton pattern, so the same instance will be returned
// every time you use this method, no matter where you're calling it from.
$logging = \Plop\Plop::getInstance();
// Now, send a log.
// Various log levels are available by default:
// debug, info, notice, warning, error, critical, alert & emergency.
// There's a method named after each log level's name.
$logging->debug('Hello world');
Log messages may contain variables, which will be replaced with their actual value when the logging method is called. This is useful in a lot of situations. For example, you can use it to apply i18n methods to the messages:
$logging = \Plop\Plop::getInstance();
$logging->error(
_('Sorry %(nick)s, now is not the time for that!'),
array(
'nick' => 'Ash',
)
);