Add guides for custom logger handlers, processors, and rules

Added new how-to documentation for extending WPGraphQL Logging with custom Monolog handlers, processors, and rules. Updated index and reference docs to link to these guides and clarified terminology and navigation. Minor improvements to existing docs for accuracy and consistency.

Author: colinmurphy

plugins/wpgraphql-logging/docs/how-to/events_pub_sub.md

@@ -119,7 +119,7 @@ Plugin::on(Events::BEFORE_RESPONSE_RETURNED, function(array $payload): void {
 ```
 
 >[!NOTE]
-> You should be able to a handler too if you want to log data to that service with the Logger Service
+> You can also add a custom handler if you want to log data to that service via the LoggerService.
 
 
 

plugins/wpgraphql-logging/docs/how-to/logger_add_new_handler.md

@@ -0,0 +1,89 @@
+## How to Add a New Handler (File Logging)
+
+This guide shows how to log to a file using a Monolog handler, either in addition to the default WordPress database handler or as a replacement. It also covers per-instance overrides.
+
+### What is a Handler?
+
+Handlers decide where logs are written. By default, WPGraphQL Logging uses a custom `WordPressDatabaseHandler` to store logs in the database. You can add more destinations (files, streams, third-party services) or replace the defaults.
+
+>[!NOTE]
+> See <https://seldaek.github.io/monolog/doc/02-handlers-formatters-processors.html> for a list of handlers and processors
+
+### Option A: Add a file handler globally (in addition to the default)
+
+Use the `wpgraphql_logging_default_handlers` filter to push a `StreamHandler` that writes to a file. The default database handler will remain enabled.
+
+```php
+<?php
+use Monolog\Handler\StreamHandler;
+use Monolog\Level;
+
+add_filter( 'wpgraphql_logging_default_handlers', function( array $handlers ) {
+    $path = WP_CONTENT_DIR . '/logs/wpgraphql_logging.log';
+    if ( ! file_exists( dirname( $path ) ) ) {
+        // Ensure directory exists
+        wp_mkdir_p( dirname( $path ) );
+    }
+
+    // Log ERROR and higher to a file, in addition to the default DB handler
+    $handlers[] = new StreamHandler( $path, Level::Error );
+    return $handlers;
+});
+```
+
+### Option B: Replace the default handler globally (file only)
+
+Return your own array of handlers from the same filter to replace the default handler entirely.
+
+```php
+<?php
+use Monolog\Handler\StreamHandler;
+use Monolog\Level;
+
+add_filter( 'wpgraphql_logging_default_handlers', function( array $handlers ) {
+    $path = WP_CONTENT_DIR . '/logs/wpgraphql_logging.log';
+    if ( ! file_exists( dirname( $path ) ) ) {
+        wp_mkdir_p( dirname( $path ) );
+    }
+
+    // Replace defaults: file handler only, log everything from DEBUG and up
+    return [ new StreamHandler( $path, Level::Debug ) ];
+});
+```
+
+### Option C: Override handlers per logger instance
+
+You can bypass the global defaults for a specific logger channel by passing handlers to `LoggerService::get_instance()`.
+
+```php
+<?php
+use Monolog\Handler\StreamHandler;
+use Monolog\Level;
+use WPGraphQL\Logging\Logger\LoggerService;
+use WPGraphQL\Logging\Logger\Handlers\WordPressDatabaseHandler;
+
+// Add file handler in addition to the DB handler for this specific channel
+$handlers = [
+    new WordPressDatabaseHandler(),
+    new StreamHandler( WP_CONTENT_DIR . '/logs/wpgraphql-channel.log', Level::Info ),
+];
+
+$logger = LoggerService::get_instance( 'file_plus_db', $handlers );
+$logger->info( 'Per-instance handlers configured' );
+
+// Or replace defaults for the instance (file only)
+$fileOnly = LoggerService::get_instance( 'file_only', [
+    new StreamHandler( WP_CONTENT_DIR . '/logs/wpgraphql-file-only.log', Level::Warning ),
+] );
+$fileOnly->warning( 'This goes only to the file' );
+```
+
+### Tips
+
+- Ensure the logs directory is writable by the web server user.
+- Consider `Monolog\\Handler\\RotatingFileHandler` to rotate files by day and limit disk usage.
+- You can combine multiple handlers (e.g., database + file + Slack) either globally (filter) or per instance.
+
+### Related
+
+- See the [Logger reference](../reference/logging.md#filter-wpgraphql_logging_default_handlers) for `wpgraphql_logging_default_handlers` and other hooks.

plugins/wpgraphql-logging/docs/how-to/logger_add_new_processor.md

@@ -0,0 +1,57 @@
+## How to Add a New Processor
+
+This guide shows how to create and register a custom processor that logs the current WordPress environment (e.g. `production`, `staging`, `development`).
+
+### What is a Processor?
+
+Processors in Monolog add or transform data on each log record before handlers write it. They can modify the `context` or `extra` arrays on a record.
+
+### Step 1: Create a processor class
+
+Create a PHP class that implements `Monolog\Processor\ProcessorInterface` and returns the updated `LogRecord`.
+
+```php
+<?php
+namespace MyPlugin\Logging;
+
+use Monolog\LogRecord;
+use Monolog\Processor\ProcessorInterface;
+
+class EnvironmentProcessor implements ProcessorInterface {
+    public function __invoke( LogRecord $record ): LogRecord {
+        $record->extra['environment'] = wp_get_environment_type();
+        return $record;
+    }
+}
+```
+
+### Step 2: Register the processor globally
+
+Use the `wpgraphql_logging_default_processors` filter to add your processor to all logger instances.
+
+```php
+<?php
+add_filter( 'wpgraphql_logging_default_processors', function( array $processors ) {
+    $processors[] = new \MyPlugin\Logging\EnvironmentProcessor();
+    return $processors;
+});
+```
+
+### (Optional) Per-instance registration
+
+Register the processor for a specific logger channel by passing it to `LoggerService::get_instance()`.
+
+```php
+<?php
+use WPGraphQL\Logging\Logger\LoggerService;
+
+$logger = LoggerService::get_instance( 'env_channel', null, [ new \MyPlugin\Logging\EnvironmentProcessor() ] );
+$logger->info( 'Environment test' );
+```
+
+
+You should see `environment` in the log record's `extra` data (e.g. in the Logs admin UI or your chosen handler output).
+
+### Related
+
+- See the [Logger reference](../reference/logging.md#filter-wpgraphql_logging_default_processors) for hooks you can use to customize processors: `wpgraphql_logging_default_processors`.

plugins/wpgraphql-logging/docs/how-to/logger_add_new_rule.md

@@ -0,0 +1,60 @@
+## How to Add a New Rule (Query must contain string)
+
+This guide shows how to create a custom logging rule that only passes when the GraphQL query contains a specific substring, and how to register it with the RuleManager.
+
+### What is a Rule?
+
+Rules implement `WPGraphQL\Logging\Logger\Rules\LoggingRuleInterface` and are evaluated by the `RuleManager`. All rules must pass for logging to proceed.
+
+Interface reference (methods):
+- `passes( array $config, ?string $query_string ): bool`
+- `get_name(): string`
+
+### Step 1: Create the rule class
+
+Create a class that implements the interface and returns true only if the query contains a given substring.
+
+```php
+<?php
+namespace MyPlugin\Logging\Rules;
+
+use WPGraphQL\Logging\Logger\Rules\LoggingRuleInterface;
+
+class ContainsStringRule implements LoggingRuleInterface {
+    public function __construct( private readonly string $needle ) {}
+
+    public function passes( array $config, ?string $query_string = null ): bool {
+        if ( ! is_string( $query_string ) || '' === trim( $query_string ) ) {
+            return false; // No query => fail
+        }
+        return stripos( $query_string, $this->needle ) !== false;
+    }
+
+    public function get_name(): string {
+        // Ensure unique name per rule; adjust if you need multiple variants
+        return 'contains_string_rule';
+    }
+}
+```
+
+### Step 2: Register the rule with the RuleManager
+
+Use the `wpgraphql_logging_rule_manager` filter to add your rule. This runs when the logger helper initializes rules.
+
+```php
+<?php
+add_filter( 'wpgraphql_logging_rule_manager', function( $rule_manager ) {
+    // Only pass when the query contains the word "GetPost"
+    $rule_manager->add_rule( new \MyPlugin\Logging\Rules\ContainsStringRule( 'GetPost' ) );
+    return $rule_manager;
+});
+```
+
+### Step 3: Verify
+
+- GraphQL requests whose query string contains `GetPost` will be logged (assuming other rules also pass).
+- Requests without that substring will be skipped by this rule, causing `is_enabled` to be false.
+
+### Related
+
+- See the [Logger reference](../reference/logging.md#filter-wpgraphql_logging_rule_manager) for the `wpgraphql_logging_rule_manager` filter.

plugins/wpgraphql-logging/docs/index.md

@@ -4,9 +4,9 @@
 
 - [Project Structure](#project-structure)
 - [Key Features](#key-features)
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Admin Interface](#admin-interface)
+- [Setup](#setup)
+- [Basic Configuration](#basic-configuration)
+- [Viewing Logs](#viewing-logs)
 - [Uninstallation and Data Cleanup](#uninstallation-and-data-cleanup)
 - [How‑to Guides](#how‑to-guides)
 - [Reference](#reference)
@@ -23,14 +23,14 @@ wpgraphql-logging/
 │   ├── Admin/                  # Admin settings, menu, and settings page logic
 │   	├── Settings/             # Admin settings functionality for displaying and saving data.
 │   ├── Events/                 # Event logging, pub/sub event manager for extending the logging.
-│   ├── Logger/                 # Logging logic, logger service, Monolog handlers & processors
-│   	├── Database/            	# Database Entity and Helper
-│   	├── Handlers/            	# Monolog WordPress Database Handler for logging data
-│   	├── Processors/           # Monolog Processors for data sanitzation and adding request headers.
-│   	├── Rules/            		# Rules and Rule Manager on whether we log a query
+│   ├── Logger/                 # Logger service, Monolog handlers & processors
+│   	├── Database/            	# Database entity and helper
+│   	├── Handlers/            	# Monolog WordPress database handler for logging data
+│   	├── Processors/           # Monolog processors for data sanitization and request headers
+│   	├── Rules/            		# Rules and RuleManager to decide whether to log a query
 │   	├── Scheduler/            # Automated data cleanup and maintenance tasks
 │   ├── Plugin.php              # Main plugin class (entry point)
-│   └── Autoload.php            # PSR-4 autoloader
+│   └── Autoloader.php          # PSR-4 autoloader
 ├── tests/                      # All test suites
 │   ├── wpunit/                 # WPBrowser/Codeception unit tests
 ├── [wpgraphql-logging.php]
@@ -100,10 +100,10 @@ Once the plugin is activated, you can activate and configure the plugin under Se
 - **Log Points**: A multi-select field to choose the specific WPGraphQL lifecycle events for which data should be logged.
 - **Log Response**: A toggle to determine whether the GraphQL response body should be included in the log. Disabling this can reduce the size of your log data.
 
->[Note]
-> The configuration for these rules are set in a rule manager service which checks to see if a event should be logged, based on whether it passes all rules or not. More docs on the rule manager can be found here @TODO
+>[!NOTE]
+> Logging enablement is determined by a set of rules managed by a `RuleManager`. All rules must pass to log a request. See the Logger reference for the RuleManager hook: [wpgraphql_logging_rule_manager](reference/logging.md#trait-loggerlogginghelper).
 
-You want to add a new rule. See our guide here @TODO
+You want to add a new rule. See: How‑to guides (`docs/how-to/logger_add_new_rule.md`).
 
 
 ### Data Management
@@ -131,7 +131,7 @@ Once configured to log data you can find logs under "GraphQL Logs" in the WordPr
 
 ![Admin View](screenshots/admin_view.png)
 
-This extends the WordPress WP List Table class but you can do the following.
+This extends the WordPress `WP_List_Table` class but you can do the following.
 
 ### Download the log
 
@@ -153,17 +153,14 @@ You can filter the log by
 
 ![Admin View with Filters](screenshots/admin_view_filters.png)
 
->[Note]
-> We only show the `info` and `error` levels as these are the only levels logged out of the box. If you need to change this, you can update the admin template. See @TODO
+>[!NOTE]
+> The default UI highlights Info and Error levels. To customize visible columns and sorting, filter `wpgraphql_logging_logs_table_column_headers` (see Admin reference).
 
 
 ### Bulk Actions
 
 Currently you can delete selected or all logs.
 
-If you want to customize this. @TODO
-
-
 
 ## Uninstallation and Data Cleanup
 
@@ -193,7 +190,11 @@ define( 'WP_GRAPHQL_LOGGING_UNINSTALL_PLUGIN', true );
 - [How to use the WPGraphQL Logging events pub/sub system](how-to/events_pub_sub.md)
 
 ### Logging
-- @TODO — add how‑to guides for LoggerService, handlers, processors, rules
+
+- [How to Add a New Handler (File Logging)](how-to/logger_add_new_handler.md)
+- [How to Add a New Processor](how-to/logger_add_new_processor.md)
+- [How to Add a New Rule (Query must contain string)](how-to/logger_add_new_rule.md)
+
 
 ## Reference
 

plugins/wpgraphql-logging/docs/reference/admin.md

@@ -2,6 +2,15 @@
 
 The WPGraphQL Logging plugin provides several filters and actions in the Admin area that allow developers to extend and customize functionality. This reference documents all available hooks with real-world examples.
 
+## Table of Contents
+
+- [SettingsPage](#class-settingspage)
+- [Settings\ConfigurationHelper](#class-settingsconfigurationhelper)
+- [Settings\SettingsFormManager](#class-settingssettingsformmanager)
+- [ViewLogsPage](#class-viewlogspage)
+- [Settings\Templates\admin.php and View Templates](#class-settingstemplatesadminphp-and-view-templates)
+
+
 ---
 
 

plugins/wpgraphql-logging/docs/reference/events.md

@@ -2,6 +2,12 @@
 
 The WPGraphQL Logging plugin exposes a lightweight pub/sub system for WPGraphQL lifecycle events and bridges them to standard WordPress actions/filters.
 
+## Table of Contents
+
+- [Events\Events](#class-eventsevents)
+- [Events\EventManager](#class-eventseventmanager)
+
+
 ---
 
 ### Class: `Events\Events`
@@ -18,7 +24,6 @@ Constants that map to WPGraphQL core hooks:
 
 Use these with the `Plugin` helpers or the `EventManager` directly.
 
-@TODO See the how to guide on logging a new event.
 
 ---