decalog / HOOKS.md

HOOKS.md in DecaLog 4.4.0, at HOOKS.md

158 lines 8.8 KB

Raw Download Zip

1	This plugin has a number of hooks that you can use, as developer or as a user, to customize the user experience or to give access to extended functionalities.
2
3	## Addition of custom actions to events in WordPress events viewers
4	It is possible to add custom actions for each event displayed in the WordPress events viewers. It can be done in the events list view or right in the single event view (the "boxed" one).
5
6	### Events list view
7	For the list view, you can use the `decalog_events_list_actions_for_event`, `decalog_events_list_actions_for_source`, `decalog_events_list_actions_for_time`, `decalog_events_list_actions_for_site`, `decalog_events_list_actions_for_user` and `decalog_events_list_actions_for_ip` filters to add (for each of the corresponding columns) a icon associated with an action (an url).
8
9	> Note "site" column is only displayed when in WordPress Multisite.
10
11	The format of the filtered value is an array of array(s). Each of the deepest array MUST contain 3 fields:
12
13	* `url`: the full url of the action to perfom. This url is opened in a new tab of the user's browser.
14	* `hint`: the text displayed while hovering the icon.
15	* `icon`: the "index" of the icon. Since DecaLog embeds the [](https://feathericons.com/Feather icon library](https://feathericons.com/](https://feathericons.com/), you can choose any index of this library.
16
17	#### Example
18	To add an "eye" icon near the IP (in list view) to perform a quick lookup of each IP with infobyip.com service:
19	```php
20	add_filter(
21	'decalog_events_list_actions_for_ip',
22	function( $actions, $item ) {
23	$actions[] = [
24	'url' => 'https://www.infobyip.com/ip-' . $item['remote_ip'] . '.html',
25	'hint' => 'Get information about this IP',
26	'icon' => 'eye',
27	];
28	return $actions;
29	},
30	10,
31	2
32	);
33	```
34
35	### Single event view
36	For the single event view, you can use the `decalog_event_view_actions_for_event`, `decalog_event_view_actions_for_content`, `decalog_event_view_actions_for_php`, `decalog_event_view_actions_for_device`, `decalog_event_view_actions_for_wp`, `decalog_event_view_actions_for_http`, `decalog_event_view_actions_for_wpbacktrace` and `decalog_event_view_actions_for_phpbacktrace` filters to add (for each of the corresponding box) a text associated with an action (an url).
37
38	The format of the filtered value is an array of array(s). Each of the deepest array MUST contain 2 fields:
39
40	* `url`: the full url of the action to perfom. This url is opened in a new tab of the user's browser.
41	* `text`: the text of the link anchor.
42
43	#### Example
44	To add a "ban" action text in the "HTTP request" box:
45	```php
46	add_filter(
47	'decalog_event_view_actions_for_http',
48	function( $actions, $item ) {
49	$actions[] = [
50	'url' => '/wp-admin/admin.php?page=ban-ip&ip=' . $item['remote_ip'],
51	'text' => 'Permanently ban ' . $item['remote_ip'],
52	];
53	return $actions;
54	},
55	10,
56	2
57	);
58	```
59
60	### Available event fields
61	Each item passed to the filter as second parameter is an array containing details about the current event. The fields are as follow:
62
63	* `logger_id` _string_: the unique logger id;
64	* `id` _integer_: the unique event id (for this specific logger id);
65	* `timestamp` _string_: the date of the event, respecting the format `Y-m-d H:i:s`;
66	* `level` _string_: the [](LOGGING.md#levelslevel](LOGGING.md#levels](LOGGING.md#levels) in {`'emergency'`, `'alert'`, `'critical'`, `'error'`, `'warning'`, `'notice'`, `'info'`, `'debug'`, `'unknown'`};
67	* `channel` _string_: the [](LOGGING.md#anatomy-of-an-eventchannel](LOGGING.md#anatomy-of-an-event](LOGGING.md#anatomy-of-an-event) in {`'cli'`, `'cron'`, `'ajax'`, `'xmlrpc'`, `'api'`, `'feed'`, `'wback'`, `'wfront'`, `'unknown'`};
68	* `class` _string_: the [](LOGGING.md#anatomy-of-an-eventclass](LOGGING.md#anatomy-of-an-event](LOGGING.md#anatomy-of-an-event) of the source in {`'core'`, `'plugin'`, `'theme'`, `'db'`, `'php'`};
69	* `component` _string_: the name of the [](LOGGING.md#anatomy-of-an-eventsource](LOGGING.md#anatomy-of-an-event](LOGGING.md#anatomy-of-an-event);
70	* `version` _string_: the version of the [](LOGGING.md#anatomy-of-an-eventsource](LOGGING.md#anatomy-of-an-event](LOGGING.md#anatomy-of-an-event);
71	* `code` _int_: the [](LOGGING.md#codeserror code](LOGGING.md#codes](LOGGING.md#codes);
72	* `message` _string_: the message associated to the event;
73	* `site_id` _integer_: the unique site id where the event was triggered;
74	* `site_name` _string_: the name of the site where the event was triggered;
75	* `user_id` _integer_: the unique user id for whom the event was triggered - may be pseudonymized;
76	* `user_name` _string_: the name of the user for whom the event was triggered - may be pseudonymized;
77	* `user_session` _string_: the user's session hash;
78	* `remote_ip` _string_: the remote IP doing the request - may be obfuscated.
79	* `country_code` _string_: the country code (iso3166/alpha2) associated with the remote IP if [](https://github.com/Pierre-Lannoy/wp-ip-locatorIP Locator](https://github.com/Pierre-Lannoy/wp-ip-locator](https://github.com/Pierre-Lannoy/wp-ip-locator) is installed, otherwise an empty string;
80	* `url` _string_: the requested local url;
81	* `verb` _string_: the verb of the inbound request in {`'get'`, `'head'`, `'post'`, `'put'`, `'delete'`, `'connect'`, `'options'`, `'trace'`, `'patch'`, `'unknown'`};
82	* `server` _string_: the target server of the inbound request;
83	* `referrer` _string_: the request referrer, if any;
84	* `user_agent` _string_: the full user agent string of the client doing the inbound request;
85	* `file` _string_: the file where the event was triggered;
86	* `line` _int_: the line where the event was triggered;
87	* `classname` _string_: the class name where the event was triggered;
88	* `function` _string_: the function where the event was triggered;
89	* `trace` _string_: the serialized full callstack triggering the event.
90
91	## Addition of custom actions to traces in WordPress traces viewers
92	It is possible to add custom actions for each trace displayed in the WordPress traces viewers. It works exactly the same way as for the events.
93
94	### Traces list view
95	For the list view, you can use the `decalog_traces_list_actions_for_trace`, `decalog_traces_list_actions_for_duration`, `decalog_traces_list_actions_for_time`, `decalog_traces_list_actions_for_site` and `decalog_traces_list_actions_for_user` filters to add (for each of the corresponding columns) a icon associated with an action (an url).
96
97	### Single trace view
98	For the single trace view, you can use the `decalog_trace_view_actions_for_trace` and `decalog_trace_view_actions_for_wp` filters to add (for each of the corresponding box) a text associated with an action (an url).
99
100	### Available trace fields
101	Each item passed to the filter as second parameter is an array containing details about the current trace. The fields are as follow:
102
103	* `logger_id` _string_: the unique logger id;
104	* `id` _integer_: the unique trace id (for this specific logger id);
105	* `trace_id` _string_: the main TraceID;
106	* `timestamp` _string_: the date of the trace, following the format `Y-m-d H:i:s`;
107	* `channel` _string_: the [](TRACING.md#anatomy-of-a-tracechannel](TRACING.md#anatomy-of-a-trace](TRACING.md#anatomy-of-a-trace) in {`'cli'`, `'cron'`, `'ajax'`, `'xmlrpc'`, `'api'`, `'feed'`, `'wback'`, `'wfront'`, `'unknown'`};
108	* `duration` _integer_: the full duration (in ms.) of the trace;
109	* `scount` _integer_: the number of spans in the trace;
110	* `site_id` _integer_: the unique site id where the trace was recorded;
111	* `site_name` _string_: the name of the site where the trace was recorded;
112	* `user_id` _integer_: the unique user id for whom the trace was recorded - may be pseudonymized;
113	* `user_name` _string_: the name of the user for whom the trace was recorded - may be pseudonymized;
114	* `user_session` _string_: the user's session hash;
115	* `spans` _string_: the serialized full spans array.
116
117	## PHP error level customization
118	PHP error levels are supernumemary compared to the logger levels. The [](https://github.com/Pierre-Lannoy/wp-decalog/blob/3.10.0/includes/listeners/class-phplistener.php#L38-L54mapping](https://github.com/Pierre-Lannoy/wp-decalog/blob/3.10.0/includes/listeners/class-phplistener.php#L38-L54](https://github.com/Pierre-Lannoy/wp-decalog/blob/3.10.0/includes/listeners/class-phplistener.php#L38-L54) translating one from the other can be customized with the `decalog_error_level_map` filter.
119
120	### Example
121	Log the `E_DEPRECATED` and `E_USER_DEPRECATED` errors as `DEBUG` level.
122	```php
123	use \Decalog\Logger;
124
125	add_filter('decalog_error_level_map', function($levels) {
126	$levels[E_DEPRECATED] = Logger::DEBUG;
127	$levels[E_USER_DEPRECATED] = Logger::DEBUG;
128	return $levels;
129	});
130	```
131
132	## Customization of PerfOps One menus
133	You can use the `poo_hide_main_menu` filter to completely hide the main PerfOps One menu or use the `poo_hide_analytics_menu`, `poo_hide_consoles_menu`, `poo_hide_insights_menu`, `poo_hide_tools_menu`, `poo_hide_records_menu` and `poo_hide_settings_menu` filters to selectively hide submenus.
134
135	### Example
136	Hide the main menu:
137	```php
138	add_filter( 'poo_hide_main_menu', '__return_true' );
139	```
140
141	## Customization of the admin bar
142	You can use the `poo_hide_adminbar` filter to completely hide this plugin's item(s) from the admin bar.
143
144	### Example
145	Remove this plugin's item(s) from the admin bar:
146	```php
147	add_filter( 'poo_hide_adminbar', '__return_true' );
148	```
149
150	## Advanced settings and controls
151	By default, advanced settings and controls are hidden to avoid cluttering admin screens. Nevertheless, if this plugin have such settings and controls, you can force them to display with `perfopsone_show_advanced` filter.
152
153	### Example
154	Display advanced settings and controls in admin screens:
155	```php
156	add_filter( 'perfopsone_show_advanced', '__return_true' );
157	```
158