Add event pub/sub and context how-to guides

Added new documentation for WPGraphQL Logging event pub/sub system and context injection (docs/how-to/events_pub_sub.md, docs/how-to/events_add_context.md), updated index and events reference docs to link and describe these features, and added a screenshot for context data. Removed unused .gitkeep from examples.

Author: colinmurphy

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

@@ -0,0 +1,79 @@
+## How to add context data to a logged WPGraphQL event
+
+This guide shows two supported ways to inject custom context data into events that WPGraphQL Logging records:
+
+- Programmatic transform API (recommended for plugins/themes using PHP namespaces)
+- WordPress filter API (easy to drop into any project)
+
+Refer to the [Events Reference](../reference/events.md) for the list of available event names.
+
+
+![Adding custom context data to WPGraphQL events](../screenshots/event_add_context_data.png)
+*Example of custom context data being added to a WPGraphQL event log entry*
+
+
+### Option A — Programmatic transform API
+
+Use the `WPGraphQL\Logging\Plugin::transform()` helper to mutate the event payload before it is logged and emitted.
+
+```php
+<?php
+use WPGraphQL\Logging\Plugin;
+use WPGraphQL\Logging\Events\Events;
+use Monolog\Level;
+
+// Add custom context to the PRE_REQUEST event
+add_action( 'init', function() {
+    Plugin::transform( Events::PRE_REQUEST, function( array $payload ): array {
+        // $payload has keys: 'context' (array) and 'level' (Monolog\Level)
+        $payload['context']['environment'] = wp_get_environment_type();
+        $payload['context']['app_id']      = 'my-headless-app';
+
+        // Optional: change the log level for this specific event
+        // $payload['level'] = Level::Debug;
+
+        return $payload;
+    }, 10 );
+} );
+```
+
+You can target any event constant from `WPGraphQL\Logging\Events\Events`, for example:
+
+- `Events::PRE_REQUEST` (maps to `do_graphql_request`)
+- `Events::BEFORE_GRAPHQL_EXECUTION` (maps to `graphql_before_execute`)
+- `Events::BEFORE_RESPONSE_RETURNED` (maps to `graphql_return_response`)
+- `Events::REQUEST_DATA` (filter `graphql_request_data`)
+- `Events::REQUEST_RESULTS` (filter `graphql_request_results`)
+- `Events::RESPONSE_HEADERS_TO_SEND` (filter `graphql_response_headers_to_send`)
+
+
+### Option B — WordPress filter API
+
+Every event also exposes a WordPress filter bridge you can hook into to modify the payload. The filter name pattern is:
+
+- `wpgraphql_logging_filter_{event_name}`
+
+Where `{event_name}` is the raw WPGraphQL hook name (the constant value). For example, to inject context before the response is returned:
+
+```php
+<?php
+add_filter( 'wpgraphql_logging_filter_graphql_return_response', function( array $payload ) {
+    // $payload has 'context' and 'level'
+    $payload['context']['trace_id']    = uniqid( 'trace_', true );
+    $payload['context']['feature_flag'] = defined('MY_FEATURE') ? (bool) MY_FEATURE : false;
+    return $payload; // You must return the modified payload
+}, 10, 1 );
+```
+
+Another example for the request data stage:
+
+```php
+<?php
+add_filter( 'wpgraphql_logging_filter_graphql_request_data', function( array $payload ) {
+    $payload['context']['client'] = [
+        'ip'      => $_SERVER['REMOTE_ADDR'] ?? null,
+        'agent'   => $_SERVER['HTTP_USER_AGENT'] ?? null,
+    ];
+    return $payload;
+}, 10, 1 );
+```

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

@@ -0,0 +1,130 @@
+## How to use the WPGraphQL Logging events pub/sub system
+
+The plugin exposes a lightweight pub/sub bus around key WPGraphQL lifecycle events and bridges them to standard WordPress actions/filters. You can:
+
+- Subscribe (read-only) to observe event payloads
+- Transform payloads before core code logs and emits them
+- Publish your own custom events for your app/plugins
+
+See the [Events Reference](../reference/events.md) for available built-in events and their mappings.
+
+
+### Core concepts
+
+- Subscribe (read-only): `Plugin::on( $event, callable $listener, $priority )`
+- Transform (mutate): `Plugin::transform( $event, callable $transform, $priority )`
+- Emit (publish): `Plugin::emit( $event, array $payload )`
+
+Priorities run ascending (lower numbers first). Transforms must return the updated payload array; subscribers receive the payload and do not return.
+
+
+### Programmatic API (recommended)
+
+```php
+<?php
+use WPGraphQL\Logging\Plugin;
+use WPGraphQL\Logging\Events\Events;
+use Monolog\Level;
+
+// 1) Subscribe (read-only) to inspect context for the pre-request event
+add_action( 'init', function() {
+    Plugin::on( Events::PRE_REQUEST, function( array $payload ): void {
+        $context = $payload['context'] ?? [];
+        // e.g., inspect or trigger side effects
+        // error_log( 'Incoming operation: ' . ( $context['operation_name'] ?? '' ) );
+    }, 10 );
+} );
+
+// 2) Transform the payload before it is logged/emitted by core code
+add_action( 'init', function() {
+    Plugin::transform( Events::BEFORE_RESPONSE_RETURNED, function( array $payload ): array {
+        $payload['context']['env']       = wp_get_environment_type();
+
+        // Optionally change severity for this event instance
+        if ( ! empty( $payload['context']['errors'] ) ) {
+            $payload['level'] = Level::Error;
+        }
+        return $payload;
+    }, 5 ); // lower priority runs earlier
+} );
+
+// 3) Emit your own custom event anywhere in your code
+add_action( 'user_register', function( $user_id ) {
+    Plugin::emit( 'my_plugin/user_registered', [
+        'context' => [ 'user_id' => (int) $user_id ],
+    ] );
+} );
+```
+
+Notes:
+
+- Built-in events are transformed internally before they are logged and then published.
+- `emit()` publishes to subscribers and the WordPress action bridge; it does not apply transforms by itself.
+  - If you want the “transform then publish” pattern for your custom event, call `EventManager::transform( $event, $payload )` yourself before publishing.
+
+
+### WordPress bridge (actions and filters)
+
+For each event, the system also fires a WordPress action and applies a WordPress filter so you can interact without the PHP helpers.
+
+- Action: `wpgraphql_logging_event_{event_name}` (fires after subscribers run)
+- Filter: `wpgraphql_logging_filter_{event_name}` (used when core transforms a payload)
+
+Examples:
+
+```php
+<?php
+// Observe the raw pre-request payload via WordPress action
+add_action( 'wpgraphql_logging_event_do_graphql_request', function( array $payload ) {
+    // e.g., send metrics to an external system
+}, 10, 1 );
+
+// Inject extra context before the response is logged
+add_filter( 'wpgraphql_logging_filter_graphql_return_response', function( array $payload ) {
+    $payload['context']['trace_id']  = uniqid( 'trace_', true );
+    $payload['context']['app_name']  = 'headless-site';
+    return $payload;
+}, 10, 1 );
+```
+
+
+### Practical example - Send data to external service
+
+```php
+<?php
+use WPGraphQL\Logging\Plugin;
+use WPGraphQL\Logging\Events\Events;
+
+Plugin::on(Events::BEFORE_RESPONSE_RETURNED, function(array $payload): void {
+	$context = $payload['context'];
+	if (array_key_exists('errors', $context)) {
+		$level = 400;
+		$level_name = 'ERROR';
+	} else {
+		$level = 200;
+		$level_name = 'INFO';
+	}
+
+
+	// Example call (replace values as needed)
+	$result = send_log_to_external_api_endpoint( [
+		'level'    => $level,
+		'level_name' => $level_name,
+		'query'    => $context['query'] ?? '',
+		'context'  => $context,
+		'message'  => 'Test'
+	] );
+}, 10);
+
+```
+
+>[!NOTE]
+> You should be able to a handler too if you want to log data to that service with the Logger Service
+
+
+
+### Troubleshooting
+
+- If your transform isn’t taking effect, ensure you’re targeting the correct event and that your callable returns the modified array.
+- If you only call `emit()`, transforms won’t run automatically; they only run where core calls `transform()`.
+- Use priorities to control ordering with other plugins (`5` runs before `10`).

plugins/wpgraphql-logging/docs/index.md

@@ -2,16 +2,14 @@
 
 ## Table of Contents
 
-@TODO - Regenerate
-
-- [Overview](#overview)
-- [Getting Started](#getting-started)
-- [Features](#features)
-- [Usage](#usage)
+- [Project Structure](#project-structure)
+- [Key Features](#key-features)
+- [Installation](#installation)
 - [Configuration](#configuration)
-- [Admin & Settings](#admin--settings)
-- [Extending the Functionality](#extending-the-functionality)
-- [Testing](#testing)
+- [Admin Interface](#admin-interface)
+- [Uninstallation and Data Cleanup](#uninstallation-and-data-cleanup)
+- [How‑to Guides](#how‑to-guides)
+- [Reference](#reference)
 
 ---
 
@@ -47,32 +45,43 @@ wpgraphql-logging/
 
 ## Key Features
 
-@TODO
-
-- **Query event lifecycle logging**
+- **End-to-end GraphQL lifecycle logging**
   - **Pre Request** (`do_graphql_request`): captures `query`, `variables`, `operation_name`.
-  - **Before Execution** (`graphql_before_execute`): includes a snapshot of request `params`.
-  - **Before Response Returned** (`graphql_return_response`): inspects `response` and automatically upgrades level to Error when GraphQL `errors` are present (adds `errors` to context when found).
+  - **Before Execution** (`graphql_before_execute`): snapshots request `params`.
+  - **Before Response Returned** (`graphql_return_response`): inspects `response`; auto-elevates level to Error when GraphQL `errors` are present (adds `errors` to context).
 
-- **Built-in pub/sub event bus**
-  - In-memory event manager with priorities: `subscribe(event, listener, priority)` and `publish(event, payload)`.
-  - Transform pipeline: `transform(event, payload)` lets you mutate `context` and `level` before logging/publishing.
+- **Developer-friendly pub/sub and transform system**
+  - Programmatic API: `Plugin::on($event, $listener)`, `Plugin::transform($event, $callable)`, `Plugin::emit($event, $payload)`.
+  - Prioritized execution: lower priority runs earlier for both subscribers and transforms.
   - WordPress bridges: actions `wpgraphql_logging_event_{event}` and filters `wpgraphql_logging_filter_{event}` to integrate with standard hooks.
+  - Safe-by-default: exceptions in listeners/transforms are caught and logged; they do not break the pipeline.
+  - See: Reference › Events (`docs/reference/events.md`) and How‑to guides (`docs/how-to/events_pub_sub.md`, `docs/how-to/events_add_context.md`).
+
+- **Extensible Monolog pipeline**
+  - Default handler: `WordPressDatabaseHandler` stores logs in `{$wpdb->prefix}wpgraphql_logging`.
+  - Add handlers via filter `wpgraphql_logging_default_handlers` (e.g., file, Slack, HTTP, etc.).
+  - Add processors via filter `wpgraphql_logging_default_processors` (e.g., enrich records with user/site data).
+  - Customize `default_context` via `wpgraphql_logging_default_context`.
+  - Use `LoggerService::get_instance()` to build custom channels, handlers, processors.
 
-- **Monolog-powered logging pipeline**
-  - Default handler: stores logs in a WordPress table (`{$wpdb->prefix}wpgraphql_logging`).
+- **Configurable rule-based logging**
+  - Built-in rules: enabled toggle, IP restrictions, exclude queries, sampling rate, null query guard, response logging toggle.
+  - All rules are orchestrated by a `RuleManager` ensuring logs only emit when all rules pass.
+  - Extend rules: hook `wpgraphql_logging_rule_manager` to add custom `LoggingRuleInterface` implementations.
 
 - **Automated data management**
-  - **Daily cleanup scheduler**: Automatically removes old logs based on retention settings.
-  - **Configurable retention period**: Set how many days to keep log data (default: 30 days).
-  - **Manual cleanup**: Admin interface to trigger immediate cleanup of old logs.
-  - **Data sanitization**: Remove sensitive fields from logged data for privacy compliance.
+  - **Daily cleanup scheduler**: removes old logs based on retention.
+  - **Configurable retention period**: choose days to keep (default 30).
+  - **Manual cleanup**: trigger from the admin UI.
+  - **Data sanitization**: built-in `DataSanitizationProcessor` removes/anonymizes/truncates sensitive fields with recommended or custom rules.
 
-- **Simple developer API**
-  - `Plugin::on()` to subscribe, `Plugin::emit()` to publish, `Plugin::transform()` to modify payloads.
+- **Admin UI for operations**
+  - Logs list view with filters (level, date range) and CSV export.
+  - Bulk delete actions and visibility controls.
 
-- **Safe-by-default listeners/transforms**
-  - Exceptions in listeners/transforms are caught and logged without breaking the pipeline.
+- **Composable and testable architecture**
+  - Clear separation: Events bus, Logger service, Rules, Processors, Handlers.
+  - Designed for extension via interfaces, filters, and helper APIs.
 
 ---
 
@@ -172,29 +181,22 @@ define( 'WP_GRAPHQL_LOGGING_UNINSTALL_PLUGIN', true );
 > **Data Loss Warning**: When `WP_GRAPHQL_LOGGING_UNINSTALL_PLUGIN` is defined as `true`, deactivating the plugin will permanently delete all logged data and drop the plugin's database tables. This action is irreversible.
 
 
-## Reference
-
-The plugin is developer focussed and can be extended in multiple ways.
-
-## Admin - (admin configuration, view and functionality)
+## How‑to Guides
 
-- [Actions/Filters](reference/admin.md)
+### Admin
 - [How to add a new Settings tab to WPGraphQL Logging](how-to/admin_add_new_tab.md)
 - [How to add a new field to an existing tab and query it](how-to/admin_add_fields.md)
 - [How to add a new column to the Logs admin grid](how-to/admin_add_view_column.md)
 
+### Events
+- [How to add context data to a logged WPGraphQL event](how-to/events_add_context.md)
+- [How to use the WPGraphQL Logging events pub/sub system](how-to/events_pub_sub.md)
 
-@TODO - How to guides
-
-## Events - (Event Management, Adding and extending events, Using the pub/sub)
-- [Actions/Filters](reference/events.md)
-
-@TODO - How to guides
-
-## Logging -  (Logging Service, Monolog Handlers & Processors, Rule Manager, Data Management)
-- [Actions/Filters](reference/logging.md)
-
-@TODO - How to guides
+### Logging
+- @TODO — add how‑to guides for LoggerService, handlers, processors, rules
 
+## Reference
 
-----
+- Admin: [Actions/Filters](reference/admin.md)
+- Events: [Actions/Filters](reference/events.md)
+- Logging: [Actions/Filters](reference/logging.md)