Download the PHP package underpin/logger-loader without Composer

Underpin Logger Loader

Loader That assists with adding loggers to a WordPress website.

Installation

Using Composer

composer require underpin/loaders/logger

Manually

This plugin uses a built-in autoloader, so as long as it is required before Underpin, it should work as-expected.

require_once(__DIR__ . '/underpin-logger/logger.php');

Setup

1. Install Underpin. See Underpin Docs
2. Register new event types as-needed.

Debug Logger

If you're logged in and add underpin_debug=1 to the end of any URL, an "Underpin events" button appears in the admin bar. This provides a debugging interface that dumps out all of the items that were registered in the request, as well as any events that were logged in that request. This context can be useful, especially in production environments where debugging can be difficult.

Event Logging Utility

This plugin includes a utility that makes it possible to log events in this plugin. These logs are written to files in the wp_uploads directory, and comes equipped with a cron job that automatically purges old logs. Additinally, the method in which the logger saves data can be extended by creating a custom Writer class.

Using the Error Logger

This plugin comes with 3 event types - error, warning, and notice. error events get written to a log, and warning or notice only display in the on-screen console when WP_DEBUG is enabled. This allows you to add a ton of notices and warnings without bogging down the system with a lot of file writing.

To write to the logger, simply chain into the logger method.

You can also log WP_Error objects directly.

Caught exceptions can be captured, too.

By default, the logger will return a Log_Item class, but you can also return a WP_Error object, instead with log_as_error

NOTE: It is considered a bad practice to make your error message contain dynamic data. This can mess with logger utilities that use logged events and cause un-necessary bloat for logging utilities that check for identical events that have happened in the past. Instead, put related data in the data array in the 4th argument.

Bad:

Good:

Gather Errors

Sometimes, you will run several functions in a row that could potentially return an error. Gather errors will lump them into a single WP_Error object, if they are actually errors.

Event Types

You can register your own custom event types if you want to log things that do not fit in any of the three defaults. A common example is when a background process runs - it would be nice to have a log of when that runs, and what happened.

To do this, you would need to create a custom event type. That is done by extending the Event_Type class.

Then, you need to add this item to your logger registry. This is usually done in the setup method inside Service_Locator

That's it! Now you can use the background process event type anywhere you want.

Writers

The Event_Type uses a class, called a Writer to write error logs to a file. Underpin comes bundled with a file writing system that works for most situations, but if for some reason you wanted your logger to write events in a different manner, a good way to-do that is by overriding the $writer_class variable of your event type.

Let's say we wanted to receive an email every time our background process logged an event. Writers can help us do that. First, we specify the namespace and class name of the writer that we're going to create.

Then, we create the class in the correct directory that matches our namespace. It should extend the Writer class.

Example

A very basic example could look something like this.

Alternatively, you can extend Event_Type and reference the extended class directly, like so: