[comment]
todo:
– screenshot of the log in action
[/comment]
As a developer you can extend Simple History in many ways.
In this tutorial you will learn how to create a simple Logger that will log all usage of the WordPress wp_mail-function. When you have created the logger you will be able to see when WordPress sends out emails, and you will also see the subject and content of each email. Pretty cool, and a great tool for debugging when and how emails are sent!
Now what is a logger?
A logger is part of the core functionality in Simple History. All you already see in Simple History is the work of different loggers:
- When you update a post and see info about that update in Simple History, that’s the work of the Post Logger.
-
When you upload an image in the media library and Simple History displays a thumbnail and information about the file type, size, and dimensions: that’s the work of the built in Media Logger.
And so on. All events that you can see in Simple History is created using different loggers.
What a logger does
A logger takes care of:
- logging things (duh!). Exactly what is up to the logger. As a general rule however you should not log to much things in one logger. For example don’t log both post updates and user logins in the same logger. One kind of thing = one logger. This approach will make your code more structured and it will make searching and filtering in Simple History easier.
-
outputting and formatting logged things. When you see the thumbnail of a uploaded image in the log, that’s the Media Logger doing its outputting and formatting work. And when you see the details of an installed plugin, that’s the plugin logger doing the same thing.
Why creating your own logger is a good idea
If you want to log many things and make them searchable and even customize the output and appearance in the history, then a “logger” in what you want to create.
Step 1: Create a plugin
The first step to create a logger for Simple History is to create the plugin that will contain all the code for the logger. If you never have created a plugin for WordPress before you might want to read Introduction to Plugin Development.
Ok. Start by creating a new file called wp_mail_logger.php and place it in the plugins folder for your WordPress installation. Add the following contents to the file to make it a WordPress plugin:
<?php /** * Plugin Name: Simple History WP Mail Logger * Description: Logger for Simple History that logs mail sent with wp_mail */
Go to the Plugins page in the WordPress admin. The new plugin should be visible there. Now activate it.
Wohoo! Now you have created a WordPress plugin. It doesn’t do anything yet, but it’s a plugin, and it’s activated, just sitting there waiting to do some cool stuff! 🙂
Step 2: Add the logger code to the plugin
Now you will add the code that makes the plugin actually do something.
Continue working in the file you created in step 1. Add the following code after the code you already have added:
/**
* Register the logger using the action "simple_history/add_custom_logger"
*/
add_action("simple_history/add_custom_logger", function($simpleHistory) {
/**
* Our logger is a class that extends the built in SimpleLogger-class
*/
class wp_mail_logger_example extends SimpleLogger {
/**
* The slug is used to identify this logger in various places.
* We use the name of the class too keep it simple.
* Please note that the slug must be max 30 chars long.
*/
public $slug = __CLASS__;
/**
* Method that returns an array with information about this logger.
* Simple History used this method to get info about the logger at various places.
*/
function getInfo() {
$arr_info = array(
"name" => "WP Mail Logger slug test",
"description" => "Logs mail sent by WordPress using the wp_mail-function"
);
return $arr_info;
}
/**
* The loaded method is called automagically when Simple History is loaded.
* Much of the init-code for a logger goes inside this method. To keep things
* simple in this example, we add almost all our code inside this method.
*/
function loaded() {
/**
* Use the "wp_mail" filter to log emails sent with wp_mail()
*/
add_filter( 'wp_mail', array( $this, "on_wp_mail" ) );
}
function on_wp_mail($args) {
$context = array(
"email_to" => $args["to"],
"email_subject" => $args["subject"],
"email_message" => $args["message"]
);
$this->info("Sent an email to '{email_to}' with subject '{email_subject}' using wp_mail()", $context);
return $args;
}
}
// Tell Simple History that we have a new logger available
$simpleHistory->register_logger("wp_mail_logger_example");
});
Step 3: Test the logger
Now we need to test the logger, i.e. we need WordPress to send an email. A quick way to do this is to create a new dummy user and make sure the checkbox to email the password is checked. So go to “Users” and choose “Add new” and when you have created the user go to the Simple History log and you should see details about the sent email. In the regular events feed you will see the subject and to whom the mail was sent. Click on the time of the event to view even more info, including the full text of the message.
And that’s that! Now you have created your first Logger. Pretty easy eh?
Check out the GitHub repository if you’re looking for more examples on how to extend Simple History.