Skip to content

Commit 81a7c69

Browse files
colinmurphycolinmurphy
committed
Added docs for Events and Logging.
1 parent 42393ef commit 81a7c69

File tree

5 files changed

+450
-17
lines changed

5 files changed

+450
-17
lines changed

‎plugins/wpgraphql-logging/README.md‎

Lines changed: 55 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ A WPGraphQL logging plugin that provides visibility into request lifecycle to he
66
* [Documentation](#getting-started)
77

88
> [!CAUTION]
9-
> This plugin is currently in development state and is not production ready.
9+
> This plugin is currently in alpha state and is not production ready but please feel free to test.
1010
1111
-----
1212

13-
@TODO - Badges
13+
@TODO
1414

1515
-----
1616

@@ -19,8 +19,9 @@ A WPGraphQL logging plugin that provides visibility into request lifecycle to he
1919
## Table of Contents
2020

2121
- [Overview](#overview)
22-
- [Features](#features)
2322
- [Getting Started](#getting-started)
23+
- [Features](#features)
24+
- [Usage](#usage)
2425
- [Configuration](#configuration)
2526
- [Extending the Functionality](#extending-the-functionality)
2627
- [Testing](#testing)
@@ -37,14 +38,16 @@ Designed with extensibility in mind, developers can easily customize and extend
3738

3839
---
3940

40-
## Features
4141

42-
@TODO
42+
## Getting Started
4343

44+
To install, you need to follow our guide here to install the plugin via composer - [https://github.com/wpengine/hwptoolkit/blob/main/docs/how-to/install-toolkit-plugins/index.md]
4445

45-
## Getting Started
46+
Once you have the composer repository setup, please run `composer req wpengine/wpgraphql-logging:*` to install the plugin.
4647

47-
@TODO
48+
Plugin should start logging data, once activated.
49+
50+
@TODO add more info once we have configuration setup.
4851

4952

5053
---
@@ -53,10 +56,10 @@ Designed with extensibility in mind, developers can easily customize and extend
5356

5457
```text
5558
wpgraphql-logging/
59+
├── docs/ # Docs for extending the plugin.
5660
├── src/ # Main plugin source code
5761
│ ├── Admin/ # Admin settings, menu, and settings page logic
58-
│ ├── Events/ # Event definitions and event dispatcher logic
59-
│ ├── Hooks/ # WordPress hooks and filters
62+
│ ├── Events/ # Event logging, pub/sub event manager for extending the logging.
6063
│ ├── Logging/ # Logging logic, logger service, Monolog handlers & processors
6164
│ ├── Plugin.php # Main plugin class (entry point)
6265
│ └── Autoload.php # PSR-4 autoloader
@@ -66,24 +69,61 @@ wpgraphql-logging/
6669
├── [activation.php]
6770
├── [composer.json]
6871
├── [deactivation.php]
69-
├── [ACTIONS_AND_FILTERS.md]
7072
├── [TESTING.md]
7173
├── [README.md]
7274
```
7375

74-
## Configuration
76+
## Features
7577

76-
@TODO - When we integrate plugin configuration.
78+
- **Query event lifecycle logging**
79+
- **Pre Request** (`do_graphql_request`): captures `query`, `variables`, `operation_name`.
80+
- **Before Execution** (`graphql_before_execute`): includes a snapshot of request `params`.
81+
- **After Execution** (`graphql_execute`): captures `response`/`ExecutionResult`, `schema`, and `request`.
82+
- **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).
7783

78-
### Settings
84+
- **Built-in pub/sub event bus**
85+
- In-memory event manager with priorities: `subscribe(event, listener, priority)` and `publish(event, payload)`.
86+
- Transform pipeline: `transform(event, payload)` lets you mutate `context` and `level` before logging/publishing.
87+
- WordPress bridges: actions `wpgraphql_logging_event_{event}` and filters `wpgraphql_logging_filter_{event}` to integrate with standard hooks.
88+
89+
- **Monolog-powered logging pipeline**
90+
- Default handler: stores logs in a WordPress table (`{$wpdb->prefix}wpgraphql_logging`).
91+
- Default processors: Memory usage, memory peak, web request, process ID, and `WPGraphQLQueryProcessor` (adds `wpgraphql_query`, `wpgraphql_operation_name`, `wpgraphql_variables`).
92+
93+
- **Simple developer API**
94+
- `Plugin::on()` to subscribe, `Plugin::emit()` to publish, `Plugin::transform()` to modify payloads.
95+
96+
- **Safe-by-default listeners/transforms**
97+
- Exceptions in listeners/transforms are caught and logged without breaking the pipeline.
98+
99+
---
100+
101+
## Usage
102+
103+
WPGraphQL Logging Plugin is highly configurable and extendable and built with developers in mind to allow them to modify, change or add data, loggers etc to this plugin. Please read the docs below:
104+
105+
106+
The following documentation is available in the `docs/` directory:
107+
108+
- [Events](docs/Events.md):
109+
Learn about the event system, available events, and how to subscribe, transform, or listen to WPGraphQL Logging events.
110+
111+
- [Logging](docs/Logging.md):
112+
Learn about the logging system, Monolog integration, handlers, processors, and how to use or extend the logger.
113+
114+
---
115+
116+
117+
118+
## Configuration
79119

80120
@TODO - When we integrate plugin configuration.
81121

82122
---
83123

84-
## Actions & Filters
124+
### Settings
85125

86-
See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehensive list of available hooks and how to use them.
126+
@TODO - When we integrate plugin configuration.
87127

88128
---
89129

‎plugins/wpgraphql-logging/composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@
8181
"/.DS_Store",
8282
"/.docker/",
8383
"/.env.dist",
84-
"/ACTIONS_AND_FILTERS.md",
84+
"/docs",
8585
"/TESTING.md",
8686
"/Thumbs.db",
8787
"/artifacts",

‎plugins/wpgraphql-logging/docs/Events.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Events in WPGraphQL Logging
2+
3+
## Table of Contents
4+
5+
- [Overview](#overview)
6+
- [Available Events](#available-events)
7+
- [Usage](#usage)
8+
- [Example 1: How to subscribe to an event](#example-1-how-to-subscribe-to-an-event)
9+
- [Example 2: How to add context to an event](#example-2-how-to-add-context-to-an-event)
10+
- [Example 3: How to run a WPGraphQL event](#example-3-how-to-run-a-wpgraphql-event)
11+
- [Example 4: Use WordPress hooks](#example-4-use-wordpress-hooks)
12+
13+
## Overview
14+
15+
WPGraphQL Logging implements a pub/sub pattern for events to subscribe to certain WPGraphQL events and allows users to subscribe/publish or transform events.
16+
17+
This is achieved in the following classes under `src/Events/`:
18+
19+
- **Events** - List of events the plugin hooks into for WPGraphQL
20+
- **EventManager** - An event manager which creates a pub/sub pattern to allow users to subscribe/publish events and also transform context or level for the current event
21+
- **QueryEventLifecycle** - The service that puts this all together and creates the logic and logs the data into the LoggerService (Monolog logger)
22+
23+
> **Note**: If we are missing anything from this event system, please feel free to create an issue or contribute.
24+
25+
## Available Events
26+
27+
Currently we subscribe to the following WPGraphQL events:
28+
29+
| Event Constant | WPGraphQL Hook | Description |
30+
| --- | --- | --- |
31+
| `Events::PRE_REQUEST` | `do_graphql_request` | Before the request is processed |
32+
| `Events::BEFORE_GRAPHQL_EXECUTION` | `graphql_before_execute` | Before query execution |
33+
| `Events::AFTER_GRAPHQL_EXECUTION` | `graphql_execute` | After query execution |
34+
| `Events::BEFORE_RESPONSE_RETURNED` | `graphql_return_response` | Before response is returned to client |
35+
36+
## Usage
37+
38+
### Example 1: How to subscribe to an event
39+
40+
**Use case** You would like to access data for a specific event.
41+
42+
**Example**
43+
44+
45+
```php
46+
<?php
47+
use WPGraphQL\Logging\Plugin;
48+
use WPGraphQL\Logging\Events\Events;
49+
50+
add_action('init', function () {
51+
Plugin::on(Events::PRE_REQUEST, function(array $payload): void {
52+
$context = $payload['context']; // array
53+
$level = $payload['level']; // string
54+
// Custom logic
55+
}, 10);
56+
});
57+
```
58+
59+
## Example 2: How to add context to an event
60+
61+
**Use case** You would like to add some custom data as a third party plugin or as a developer to be logged as part of the lifecycle.
62+
63+
**Example**
64+
65+
```php
66+
<?php
67+
use WPGraphQL\Logging\Plugin;
68+
use WPGraphQL\Logging\Events\Events;
69+
use Monolog\Level;
70+
71+
add_action('init', function () {
72+
Plugin::transform(Events::BEFORE_RESPONSE_RETURNED, function(array $payload): array {
73+
74+
// Add some custom context
75+
$payload['context']['custom_key'] = 'custom_value';
76+
77+
// Set the level to debug
78+
$payload['level'] = Level::Debug;
79+
80+
return $payload;
81+
}, 10);
82+
});
83+
```
84+
85+
### Example 3: How to run a WPGraphQL event
86+
87+
**Use case:** The current list of events that the plugin subscribes too does not give enough information or you need to subscribe to a particular event which is problematic.
88+
89+
**Example**
90+
91+
Currently the plugin logs at four points in the WPGraphQL lifecycle: `do_graphql_request`, `graphql_before_execute`, `graphql_execute`, `graphql_return_response`. If you need more visibility you could do the following:
92+
93+
```php
94+
use WPGraphQL\Logging\Logger\LoggerService;
95+
96+
add_action('graphql_pre_resolve_field', function($source, $args, $context, $info) {
97+
LoggerService::get_instance()->info('Resolving field', [
98+
'field' => $info->fieldName ?? '',
99+
'type' => method_exists($info, 'parentType') ? (string) $info->parentType : '',
100+
]);
101+
}, 10, 4);
102+
103+
```
104+
105+
### Example 4. Use WordPress hooks
106+
107+
In addition to the internal API, every event also triggers standard WordPress hooks:
108+
109+
- Action: `wpgraphql_logging_event_{event_name}` receives the published payload
110+
- Filter: `wpgraphql_logging_filter_{event_name}` can modify the payload before logging
111+
112+
```php
113+
<?php
114+
// Listen via WordPress action
115+
add_action('wpgraphql_logging_event_do_graphql_request', function(array $payload) {
116+
// ...
117+
}, 10, 1);
118+
119+
// Transform via WordPress filter
120+
add_filter('wpgraphql_logging_filter_graphql_return_response', function(array $payload) {
121+
// ... mutate $payload
122+
return $payload;
123+
}, 10, 1);
124+
```
125+
126+
## Further Reading
127+
128+
- [WPGraphQL Documentation](https://www.wpgraphql.com/docs/)
129+
- [WPGraphQL Actions and Filters](https://www.wpgraphql.com/docs/actions-and-filters/)
130+
- [Observer Pattern](https://en.wikipedia.org/wiki/Observer_pattern)
131+
- [Publish-Subscribe Pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern)
132+
- [WordPress Plugin API (Actions & Filters)](https://developer.wordpress.org/plugins/hooks/)
133+
- [Event-Driven Architecture](https://martinfowler.com/articles/201701-event-driven.html)

0 commit comments

Comments
 (0)