From 03910414bae1d8a6ea8066f627d4ba17fb9a7b52 Mon Sep 17 00:00:00 2001 From: BenceSzalai Date: Sun, 29 Nov 2020 13:46:46 +0100 Subject: [PATCH] Improve: README.md and CHANGELOG.md --- CHANGELOG.md | 2 +- README.md | 65 ++++++++++------------- src/WordPressHandler/WordPressHandler.php | 2 +- 3 files changed, 31 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6aa9cf0..ebeecec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -75,7 +75,7 @@ No changelog had been maintained up to this point. Refer to the GIT commit histo [2.1.0]: https://github.com/bradmkjr/monolog-wordpress/tree/2.1.0 [2.0.1]: https://github.com/bradmkjr/monolog-wordpress/tree/2.0.1 [2.0.0]: https://github.com/bradmkjr/monolog-wordpress/tree/2.0.0 -[v1 changes after v2 release]: https://github.com/bradmkjr/monolog-wordpress/compare/1.6.4...v2 +[v1 changes after v2 release]: https://github.com/bradmkjr/monolog-wordpress/compare/1.6.4...v1 [1.6.4]: https://github.com/bradmkjr/monolog-wordpress/tree/1.6.4 [1.6.3]: https://github.com/bradmkjr/monolog-wordpress/tree/1.6.3 [1.6.2]: https://github.com/bradmkjr/monolog-wordpress/tree/1.6.2 diff --git a/README.md b/README.md index b820de5..40b99a4 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Original based on: Homepage: http://www.d-herrmann.de/projects/monolog-mysql-handler/ # Disclaimer -This is a very simple handler for monolog. This version works for custom plugin development, but I would not advise to distrubte this code in a public repository for general use on high traffic sites. You have been warned. +This is a very simple handler for monolog. This version works for custom plugin development, but I would not advise to distribute this code in a public repository for general use on high traffic sites. You have been warned. # Installation monolog-wordpress is available via composer. Just add the following line to your required section in composer.json and do a `php composer.phar update` or your choice of composer update method. @@ -26,29 +26,26 @@ Since Monolog v2 broke compatibility with PHP versions before v7.1 some may want Apart from the compatibility differences stated above the features of v1 and v2 are going to be kept the same as much as possible. # Usage -Just use it as any other Monolog Handler, push it to the stack of your Monolog Logger instance. The Handler however needs some parameters: +Just use it as any other Monolog Handler, push it to the stack of your Monolog Logger instance. The Handler however has some parameters: -- **$wpdb** Global instance of your DB connection. -- **$table** The table name where the logs should be stored -- **$additionalFields** simple array of additional database fields, which should be stored in the database. The columns are created automatically, and the fields can later be used in the extra context section of a record. See examples below. _Defaults to an empty array()_ -- **$level** can be any of the standard Monolog logging levels. Use Monologs statically defined contexts. _Defaults to Logger::DEBUG_ -- **$bubble** _Defaults to true_ +- `$wpdb`: The instance of your DB connection. To use the global connection of WordPress, use `null`. Otherwise, use a `\wpdb` instance. _Default: `null`_ +- `$table`: Name of the database table to store the logs in. The 'wp_' (or other configured) prefix will be added automatically. _Default: `'logs'`_ +- `$additionalFields`: simple array of additional database fields, which should be stored in the database. The columns are created automatically, and the fields can later be used in the extra context section of a record. See examples below. _Defaults to an empty `array()`_ +- `$level`: The minimum logging level at which this handler will be triggered. Can be any of the standard Monolog logging levels. Use Monologs statically defined contexts. _Defaults to `Logger::DEBUG`_ +- `$bubble`: Whether the messages that are handled can bubble up the stack or not. _Defaults to `true`_ # Examples -Given that $wpdb is your database instance, you could use the class as follows: +Given that the global `$wpdb` is your database instance, you could use the class as follows: ```php // Import class use WordPressHandler\WordPressHandler; -// Ensure access to global $wpdb -global $wpdb; - // Create WordPressHandler -$wordPressHandler = new WordPressHandler($wpdb, "log", array('username', 'userid'), \Monolog\Logger::DEBUG); +$wordPressHandler = new WordPressHandler(null, "log", ['username', 'userid'], \Monolog\Logger::DEBUG); // Configure maximum number of rows to keep (old entries are deleted when reached) -$wordPressHandler->set_max_table_rows( 250000 ); +$wordPressHandler->conf_table_size_limiter( 250000 ); // Setup array of extra fields $record = ['extra' => []]; @@ -64,7 +61,7 @@ $logger = new \Monolog\Logger($context); $logger->pushHandler($wordPressHandler); // Now you can use the logger, and further attach additional information -$logger->addWarning("This is a great message, woohoo!", array('username' => 'John Doe', 'userid' => 245)); +$logger->warning("This is a great message, woohoo!", ['username' => 'John Doe', 'userid' => 245]); ``` Required code to set up tables on plugin activation: @@ -73,33 +70,34 @@ Required code to set up tables on plugin activation: require __DIR__.'/vendor/autoload.php'; // Create the logs table if it doesn't already exist on plugin activation -function register_activation_hook(__FILE__, function() { - global $wpdb; - +register_activation_hook(__FILE__, 'my_plugin_activation'); +function my_plugin_activation() { $handler = new \WordPressHandler\WordPressHandler( - $wpdb, "logs", + null, "logs", array('username', 'userid'), \Monolog\Logger::DEBUG ); // setup array of extra fields - $record = ['extra' => []]; + $record = array('extra' => array()); // creates database table if needed, add extra fields from above $handler->initialize($record); -}); +} +``` -// Now somewhere else in my plugin where I want to use the logger +Now somewhere else in my plugin where I want to use the logger: +```php $logger = new \Monolog\Logger('channel'); $handler = new \WordPressHandler\WordPressHandler( - $wpdb, "logs", + null, "logs", [], \Monolog\Logger::DEBUG ); $handler->initialized = true; // Don't do any extra work - we've already done it. $logger->pushHandler($handler); -$logger->warn('Some message'); +$logger->warning('Some message'); ``` Example code to delete tables on plugin deactivation: @@ -109,10 +107,9 @@ register_uninstall_hook(__FILE__, 'my_plugin_uninstall'); function my_plugin_uninstall() { require __DIR__."/vendor/autoload.php"; - global $wpdb; $handler = new \WordPressHandler\WordPressHandler( - $wpdb, "logs", + null, "logs", [], \Monolog\Logger::DEBUG ); @@ -124,18 +121,14 @@ function my_plugin_uninstall() Example to use in your custom WordPress Plugin ```php +use WordPressHandler\WordPressHandler; + +require __DIR__ . '/vendor/autoload.php'; + add_action( 'plugins_loaded', 'demo_function' ); function demo_function(){ - require __DIR__ . '/vendor/autoload.php'; - - // Import class - use WordPressHandler\WordPressHandler; - - // Ensure access to global $wpdb - global $wpdb; - - // Create WordPressHandler - $wordPressHandler = new WordPressHandler($wpdb, "log", array('app', 'version'), \Monolog\Logger::DEBUG); + // Create a WordPressHandler instance + $wordPressHandler = new WordPressHandler(null, "log", ['app', 'version'], \Monolog\Logger::DEBUG); // Create logger $context = 'test-plugin-logging'; @@ -145,7 +138,7 @@ function demo_function(){ $logger->pushHandler($wordPressHandler); // Now you can use the logger, and further attach additional information - $logger->addWarning("This is a great message, woohoo!", array('app' => 'Test Plugin', 'version' => '2.4.5')); + $logger->warning("This is a great message, woohoo!", ['app' => 'Test Plugin', 'version' => '2.4.5']); } ``` diff --git a/src/WordPressHandler/WordPressHandler.php b/src/WordPressHandler/WordPressHandler.php index 7a5dd58..548f168 100644 --- a/src/WordPressHandler/WordPressHandler.php +++ b/src/WordPressHandler/WordPressHandler.php @@ -52,7 +52,7 @@ class WordPressHandler extends AbstractProcessingHandler * @param \wpdb|null $custom_wpdb The {@see \wpdb} object of database connection. * Set to `null` to automatically use the global $wpdb of WordPress. * Default: null - * @param string $table Name of the table in the database to store the logs in. + * @param string $table Name of the database table to store the logs in. * The 'wp_' (or other configured) prefix will be added automatically. * Default: 'logs' * @param string[] $additionalFields Additional Context Parameters to store in database