More imported docs.

johnbillion · Oct 30, 2023 · 1f65a97 · 1f65a97
1 parent c4f890d
commit 1f65a97
Show file tree

Hide file tree

Showing 16 changed files with 164 additions and 2 deletions.
diff --git a/docs/assets/banner-1544x500.png b/docs/assets/banner-1544x500.png
diff --git a/docs/assets/block-timing.png b/docs/assets/block-timing.png
diff --git a/docs/assets/hooks-caps.png b/docs/assets/hooks-caps.png
diff --git a/docs/assets/hooks-request-1.png b/docs/assets/hooks-request-1.png
diff --git a/docs/assets/jed.png b/docs/assets/jed.png
diff --git a/docs/assets/screenshot-8.png b/docs/assets/screenshot-8.png
diff --git a/docs/assets/screenshot-9.png b/docs/assets/screenshot-9.png
diff --git a/docs/assets/wp-die-generic.png b/docs/assets/wp-die-generic.png
diff --git a/docs/assets/wp-die-stack.png b/docs/assets/wp-die-stack.png
diff --git a/docs/wordpress-debugging/blocks.md b/docs/wordpress-debugging/blocks.md
@@ -0,0 +1,12 @@
+---
+title: Blocks
+parent: WordPress debugging
+---
+
+# Debugging blocks in Query Monitor
+
+The Blocks panel in Query Monitor lists all of the blocks on the current page, along with their attributes and other debugging information. Nested blocks (for example for groups or columns) are fully supported.
+
+[![Screenshot of the Blocks panel in Query Monitor](/assets/block-timing.png)](/assets/block-timing.png)
+
+If you're developing dynamic blocks, the block render callback and render timing information will help you keep an eye on performance that can otherwise be difficult to measure.
diff --git a/docs/wordpress-debugging/javascript-translation-files.md b/docs/wordpress-debugging/javascript-translation-files.md
@@ -0,0 +1,14 @@
+---
+title: Translation files
+parent: WordPress debugging
+---
+
+# Debugging translation files in Query Monitor
+
+<!-- @todo docs about PHP/MO/PO translations -->
+
+[WordPress 5.0 introduced the ability to use internationalisation functions in JavaScript and provide Jed translations for messages that use them](https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/).
+
+Query Monitor fully supports debugging the loading of these translation files in the Languages panel, so you know which files WordPress is attempting to load:
+
+[![Screenshot of the Languages panel in Query Monitor showing the Jed translation files that WordPress attempts to load](/assets/jed.png)](/assets/jed.png)
diff --git a/docs/wordpress-debugging/profiling-and-logging.md b/docs/wordpress-debugging/profiling-and-logging.md
@@ -0,0 +1,103 @@
+---
+title: Profiling and logging
+parent: WordPress debugging
+redirect_from: /blog/2018/07/profiling-and-logging/
+---
+
+# Profiling and logging in Query Monitor
+
+Query Monitor allows developers to profile the running time and memory usage of their code and to log debugging messages to the Query Monitor interface.
+
+Let's take a look at profiling and logging in detail.
+
+## Profiling
+
+Basic profiling can be performed and displayed in the Timings panel in Query Monitor using actions in your code:
+
+```php
+// Start the 'foo' timer:
+do_action( 'qm/start', 'foo' );
+
+// Run some code
+my_potentially_slow_function();
+
+// Stop the 'foo' timer:
+do_action( 'qm/stop', 'foo' );
+```
+
+The time taken and approximate memory usage used between the `qm/start` and `qm/stop` actions for the given function name will be recorded and shown in the Timings panel. Timers can be nested, although be aware that this reduces the accuracy of the memory usage calculations.
+
+Timers can also make use of laps with the `qm/lap` action:
+
+```php
+// Start the 'bar' timer:
+do_action( 'qm/start', 'bar' );
+
+// Iterate over some data:
+foreach ( range( 1, 10 ) as $i ) {
+    my_potentially_slow_function( $i );
+    do_action( 'qm/lap', 'bar' );
+}
+
+// Stop the 'bar' timer:
+do_action( 'qm/stop', 'bar' );
+```
+
+Here's what the Timing panel looks like:
+
+[![Query Monitor's Timing Panel](/assets/screenshot-8.png)](/assets/screenshot-8.png)
+
+Note that the times and memory usage displayed in the Timings panel should be treated as approximations, because they are recorded at the PHP level and can be skewed by your environment and by other code. If you require highly accurate timings, you'll need to use a low level profiling tool such as XHProf.
+
+## Logging
+
+Debugging messages can be sent to the Logs panel in Query Monitor using actions in your code:
+
+```php
+do_action( 'qm/debug', 'This happened!' );
+```
+
+You can use any of the following actions which correspond to PSR-3 and syslog log levels:
+
+* `qm/emergency`
+* `qm/alert`
+* `qm/critical`
+* `qm/error`
+* `qm/warning`
+* `qm/notice`
+* `qm/info`
+* `qm/debug`
+
+A log level of `warning` or higher will trigger a notification in Query Monitor's admin toolbar.
+
+Here's what the Logs panel looks like:
+
+[![Query Monitor's Logging Panel](/assets/screenshot-9.png)](/assets/screenshot-9.png)
+
+Contextual interpolation can be used via the curly brace syntax:
+
+```php
+do_action( 'qm/warning', 'Unexpected value of {foo} encountered', [
+    'foo' => $foo,
+] );
+```
+
+A `WP_Error` or `Exception` object can be passed directly into the logger:
+
+```php
+if ( is_wp_error( $response ) ) {
+    do_action( 'qm/error', $response );
+}
+
+try {
+    // your code
+} catch ( Exception $e ) {
+    do_action( 'qm/error', $e );
+}
+```
+
+Finally, the static logging methods on the `QM` class can be used instead of calling `do_action()`:
+
+```php
+QM::error( 'Everything is broken' );
+```
diff --git a/docs/wordpress-debugging/related-hooks.md b/docs/wordpress-debugging/related-hooks.md
@@ -0,0 +1,21 @@
+---
+title: Related hooks
+parent: WordPress debugging
+redirect_from: /blog/2019/02/new-features-in-query-monitor-3-3/
+---
+
+# Related hooks with filters or actions attached
+
+Many of the panels in Query Monitor include a sub-menu which lists related hooks where filters or actions are attached to them. This can greatly reduce the amount of time you spend trying to find out what's making changes to certain behaviour on your site.
+
+I've found this to be particularly helpful on the Request panel, which tracks hooks related to rewrite rules, query parsing, request handling, query vars, and more.
+
+[![Screenshot of the "Hooks in Use" sub-menu of the Request panel in Query Monitor](/assets/hooks-request-1.png)](/assets/hooks-request-1.png)
+
+It's also very useful for figuring out what's making changes to user role and capability handling on your site:
+
+[![Screenshot of the "Hooks in Use" sub-menu of the Capability Checks panel in Query Monitor](/assets/hooks-caps.png)](/assets/hooks-caps.png)
+
+Some panels track certain option names too, which means all the filters related to that option get automatically tracked. For example, you'll be able to see if something is hooked onto the `pre_option_stylesheet` filter on the Template panel, or the `site_option_WPLANG` filter on the Languages panel.
+
+Not all of the panels are tracking related hooks yet. I'll continue expanding and improving this feature in future releases of QM, including adding a way to expose all of the hooks that each panel is tracking, regardless of whether filters or actions are attached to them.
diff --git a/docs/wordpress-debugging/rest-api-requests.md b/docs/wordpress-debugging/rest-api-requests.md
@@ -2,7 +2,6 @@
 title: Rest API requests
 parent: WordPress debugging
 redirect_from: /blog/2021/05/debugging-wordpress-rest-api-requests/
-nav_order: 3
 ---
 
 # Debugging WordPress REST API requests with Query Monitor

diff --git a/docs/wordpress-debugging/template-part-loading.md b/docs/wordpress-debugging/template-part-loading.md
@@ -2,7 +2,6 @@
 title: Template part loading
 parent: WordPress debugging
 redirect_from: /blog/2019/07/debugging-wordpress-template-part-loading/
-nav_order: 2
 ---
 
 # Debugging WordPress template part loading with Query Monitor

diff --git a/docs/wordpress-debugging/wp-die.md b/docs/wordpress-debugging/wp-die.md
@@ -0,0 +1,14 @@
+---
+title: wp_die()
+parent: WordPress debugging
+---
+
+# wp_die() debugging in Query Monitor
+
+The `wp_die()` output in WordPress is a thing of beauty... if you’re into minimalism.
+
+[![Screenshot of the useless output of a call to wp_die()](/assets/wp-die-generic.png)](/assets/wp-die-generic.png)
+
+Query Monitor adds some debugging information to the output of `wp_die()`, including the component responsible and the call stack, to help you identify the source of the message:
+
+[![Screenshot of a slightly more useful output of a call to wp_die() with Query Monitor enabled](/assets/wp-die-stack.png)](/assets/wp-die-stack.png)