{"id":21611522,"url":"https://github.com/underpin-wp/logger-loader","last_synced_at":"2025-04-11T05:34:21.092Z","repository":{"id":48196305,"uuid":"363805218","full_name":"Underpin-WP/logger-loader","owner":"Underpin-WP","description":"Logger Utility ","archived":false,"fork":false,"pushed_at":"2021-11-22T12:24:58.000Z","size":52,"stargazers_count":2,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T03:34:43.670Z","etag":null,"topics":["error-log","event-log","hacktoberfest","underpin","wordpress"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Underpin-WP.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-03T03:19:12.000Z","updated_at":"2023-07-20T10:50:44.000Z","dependencies_parsed_at":"2022-09-09T05:50:44.721Z","dependency_job_id":null,"html_url":"https://github.com/Underpin-WP/logger-loader","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Flogger-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Flogger-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Flogger-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Underpin-WP%2Flogger-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Underpin-WP","download_url":"https://codeload.github.com/Underpin-WP/logger-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248348078,"owners_count":21088804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-log","event-log","hacktoberfest","underpin","wordpress"],"created_at":"2024-11-24T21:13:00.344Z","updated_at":"2025-04-11T05:34:21.068Z","avatar_url":"https://github.com/Underpin-WP.png","language":"PHP","readme":"# Underpin Logger Loader\n\nLoader That assists with adding loggers to a WordPress website.\n\n## Installation\n\n### Using Composer\n\n`composer require underpin/loaders/logger`\n\n### Manually\n\nThis plugin uses a built-in autoloader, so as long as it is required _before_\nUnderpin, it should work as-expected.\n\n`require_once(__DIR__ . '/underpin-logger/logger.php');`\n\n## Setup\n\n1. Install Underpin. See [Underpin Docs](https://www.github.com/underpin-wp/underpin)\n1. Register new event types as-needed.\n\n\n## Debug Logger\nIf 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.\n\n## Event Logging Utility\n\nThis plugin includes a utility that makes it possible to log events in this plugin. These logs are written to files in\nthe `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.\n\n### Using the Error Logger\n\nThis plugin comes with 3 event types - `error`, `warning`, and `notice`. `error` events get written to a log,\nand `warning` or `notice` only display in the on-screen console when `WP_DEBUG` is enabled. This allows you to add\na ton of `notices` and `warnings` without bogging down the system with a lot of file writing.\n\nTo write to the logger, simply chain into the `logger` method.\n\n```php\nplugin_name_replace_me()-\u003elogger()-\u003elog(\n'error',\n'error_code',\n'error_message',\n['arbitrary' =\u003e 'data', 'that' =\u003e 'is relevant', 'ref' =\u003e 1]\n);\n```\n\nYou can also log `WP_Error` objects directly.\n\n```php\n$error = new \\WP_Error('code','Message',['data' =\u003e 'to use']);\nplugin_name_replace_me()-\u003elogger()-\u003elog_wp_error('error',$error);\n```\n\nCaught exceptions can be captured, too.\n\n```php\ntry{\n  echo 'hi';\n}catch(Exception $e ){\n  plugin_name_replace_me()-\u003elogger()-\u003elog_exception('error', $e);\n}\n```\n\nBy default, the logger will return a `Log_Item` class, but you can also _return_ a `WP_Error` object, instead with `log_as_error`\n\n```php\n$wp_error_object = plugin_name_replace_me()-\u003elogger()-\u003elog_as_error(\n  'error',\n  'error_code',\n  'error message',\n  ['arbitrary' =\u003e 'data', 'that' =\u003e 'is relevant']\n);\n\nvar_dump($wp_error_object); // WP_Error...\n```\n\n**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.\n\n**Bad:**\n\n\n```php\n$wp_error_object = plugin_name_replace_me()-\u003elogger()-\u003elog_as_error(\n  'error',\n  'invalid_product',\n  'The product ID ' . $id . ' is invalid'\n);\n```\n\n**Good:**\n\n```php\n$wp_error_object = plugin_name_replace_me()-\u003elogger()-\u003elog_as_error(\n  'error',\n  'invalid_product',\n  'An invalid product was referenced',\n  ['product_id' =\u003e $id]\n);\n```\n\n\n### Gather Errors\n\nSometimes, you will run several functions in a row that could potentially return an error. Gather errors will lump them\ninto a single `WP_Error` object, if they are actually errors.\n\n```php\n$item_1 = function_that_returns_errors();\n$item_2 = another_function_that_returns_errors();\n\n$errors = underpin()-\u003elogger()-\u003egather_errors($item_1,$item_2);\n\nif($errors-\u003ehas_errors()){\n  // Do do something if either of the items were a WP Error.\n} else{\n // All clear, proceed.\n}\n```\n\n### Event Types\n\nYou can register your own custom event types if you want to log things that do not fit in any of the three defaults. A\ncommon example is when a background process runs - it would be nice to have a log of when that runs, and what happened.\n\nTo do this, you would need to create a custom event type. That is done by extending the `Event_Type` class.\n\n```php\n\nnamespace Plugin_Name_Replace_Me\\Event_Types;\n/**\n * Class Background_Process\n * Error event type.\n *\n * @since 1.0.0\n *\n * @since\n * @package\n */\nclass Background_Process extends Event_Type {\n\n\t/**\n\t * Event type\n\t *\n\t * @since 1.0.0\n\t *\n\t * @var string\n\t */\n\tpublic $type = 'background_process';\n\n\t/**\n\t * Writes this to the log.\n\t * Set this to true to cause this event to get written to the log.\n\t *\n\t * @since 1.0.0\n\t *\n\t * @var bool\n\t */\n\tprotected $write_to_log = true;\n\n\t/**\n\t * @var inheritDoc\n\t */\n\tpublic $description = 'Logs when background processes run.';\n\n\t/**\n\t * @var inheritDoc\n\t */\n\tpublic $name = \"Background Processes\";\n}\n```\n\nThen, you need to add this item to your logger registry. This is usually done in the `setup` method inside `Service_Locator`\n\n```php\n\t/**\n\t * Set up active loader classes.\n\t *\n\t * This is where you can add anything that needs \"registered\" to WordPress,\n\t * such as shortcodes, rest endpoints, blocks, and cron jobs.\n\t *\n\t * All supported loaders come pre-packaged with this plugin, they just need un-commented here\n\t * to begin using.\n\t *\n\t * @since 1.0.0\n\t */\n\tprotected function _setup() {\n      plugin_name_replace_me()-\u003elogger()-\u003eadd('background_process', '\\Plugin_Name_Replace_Me\\Event_Types\\Background_Process');\n\t}\n```\n\nThat's it! Now you can use the background process event type anywhere you want.\n\n### Writers\n\nThe Event_Type uses a class, called a `Writer` to write error logs to a file. Underpin comes bundled with a file writing\nsystem that works for most situations, but if for some reason you wanted your logger to write events in a different manner,\na good way to-do that is by overriding the `$writer_class` variable of your event type.\n\nLet's say we wanted to receive an email every time our background process logged an event. Writers can help us do that.\nFirst, we specify the namespace and class name of the writer that we're going to create.\n\n```php\n\nnamespace Plugin_Name_Replace_Me\\Event_Types;\n/**\n * Class Background_Process\n * Error event type.\n *\n * @since 1.0.0\n *\n * @since\n * @package\n */\nclass Background_Process extends Event_Type {\n\n\t/**\n\t * Event type\n\t *\n\t * @since 1.0.0\n\t *\n\t * @var string\n\t */\n\tpublic $type = 'background_process';\n\n\t/**\n\t * Writes this to the log.\n\t * Set this to true to cause this event to get written to the log.\n\t *\n\t * @since 1.0.0\n\t *\n\t * @var bool\n\t */\n\tprotected $write_to_log = true;\n\n\t/**\n\t * @var inheritDoc\n\t */\n\tpublic $description = 'Logs when background processes run.';\n\n\t/**\n\t * @var inheritDoc\n\t */\n\tpublic $name = \"Background Processes\";\n\n\n\t/**\n\t * The class to instantiate when writing to the error log.\n\t *\n\t * @since 1.0.0\n\t *\n\t * @var string Namespaced instance of writer class.\n\t */\n\tpublic $writer_class = 'Plugin_Name_Replace_Me\\Factories\\Email_Logger';\n}\n```\n\nThen, we create the class in the correct directory that matches our namespace. It should extend the `Writer` class.\n\n## Example\n\nA very basic example could look something like this.\n\n```php\nunderpin()-\u003escripts()-\u003eadd( 'test', [\n\t'handle'      =\u003e 'test',\n\t'src'         =\u003e 'path/to/script/src',\n\t'name'        =\u003e 'test',\n\t'description' =\u003e 'The description',\n] );\n```\n\nAlternatively, you can extend `Event_Type` and reference the extended class directly, like so:\n\n```php\nunderpin()-\u003elogger()-\u003eadd('key','Namespace\\To\\Class');\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funderpin-wp%2Flogger-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funderpin-wp%2Flogger-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funderpin-wp%2Flogger-loader/lists"}