From 8c550a274f938da5ccdf3a32e14587a688bf727c Mon Sep 17 00:00:00 2001
From: Clement Boirie <cboirie@beapi.fr>
Date: Mon, 24 Jun 2024 22:21:57 +0200
Subject: [PATCH 1/4] docs: add documentation for `WordPress.DB.SlowDBQuery`

---
 WordPress/Docs/DB/SlowDBQueryStandard.xml | 83 +++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 WordPress/Docs/DB/SlowDBQueryStandard.xml

diff --git a/WordPress/Docs/DB/SlowDBQueryStandard.xml b/WordPress/Docs/DB/SlowDBQueryStandard.xml
new file mode 100644
index 0000000000..93dbbb6b83
--- /dev/null
+++ b/WordPress/Docs/DB/SlowDBQueryStandard.xml
@@ -0,0 +1,83 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Slow DB Query"
+    >
+    <standard>
+    <![CDATA[
+    For performance reason, it's recommended to avoid doing lots of meta queries.
+    The underlying SQL request generated by those queries can be extremely slow queries especially for complexe meta query.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using tax_query to retrieve a list of posts">
+        <![CDATA[
+$query = new WP_Query(
+    array(
+        'tax_query' => array(
+            array(
+                'taxonomy' => 'color',
+                'field'    => 'slug',
+                'terms'    => array(
+                    'blue',
+                    'red',
+                )
+            )
+        )
+    )
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using meta_query to retrieve a list of posts">
+        <![CDATA[
+$query = new WP_Query(
+    array(
+        'meta_query' => array(
+            array(
+                'key'     => 'color',
+                'compare' => 'IN',
+                'value'   => array(
+                    'blue',
+                    'red',
+                )
+            )
+        )
+    )
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <code_comparison>
+        <code title="Valid: in case of binary metadata (true/false) check if meta_key exist and remove it otherwise">
+        <![CDATA[
+// mark post 123 as "featured"
+update_post_meta( 123, 'is_featured', true );
+
+// remove "featured" state for post 456
+delete_post_meta( 456, 'is_featured' );
+
+$query = new WP_Query(
+    array(
+        'meta_key' => 'is_featured'
+    ),
+);
+        ]]>
+        </code>
+        <code title="Invalid: check for the value of a binary metadata, which is slower">
+        <![CDATA[
+// mark post 123 as "featured"
+update_post_meta( 123, 'is_featured', true );
+
+// mark post 456 as not "featured"
+update_post_meta( 456, 'is_featured', false );
+
+$query = new WP_Query(
+    array(
+        'meta_key' => 'is_featured',
+        'meta_value' => true
+    ),
+);
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>

From 585ebfcb64a585337e84240a87dfb64bbaf57967 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 10 Feb 2026 10:56:53 -0300
Subject: [PATCH 2/4] Improve documentation for `WordPress.DB.SlowDBQuery`

- Rewrite standard text to mention all four flagged keys, clarify
  that both array assignments and query-parameter strings are
  detected.
- Replace code examples with examples that stay within 48-character
  limit and use `<em>` tags.
- Remove second code comparison that incorrectly showed
  `tax_query` and `meta_key` as valid when the sniff warns on all
  four keys.
---
 WordPress/Docs/DB/SlowDBQueryStandard.xml | 72 ++++-------------------
 1 file changed, 11 insertions(+), 61 deletions(-)

diff --git a/WordPress/Docs/DB/SlowDBQueryStandard.xml b/WordPress/Docs/DB/SlowDBQueryStandard.xml
index 93dbbb6b83..79d10e4b95 100644
--- a/WordPress/Docs/DB/SlowDBQueryStandard.xml
+++ b/WordPress/Docs/DB/SlowDBQueryStandard.xml
@@ -5,78 +5,28 @@
     >
     <standard>
     <![CDATA[
-    For performance reason, it's recommended to avoid doing lots of meta queries.
-    The underlying SQL request generated by those queries can be extremely slow queries especially for complexe meta query.
+    Usage of the meta_query, meta_key, meta_value, and tax_query keys in array assignments and query-parameter strings is discouraged and should be carefully evaluated. When passed to WordPress database query APIs, these keys can lead to slow queries, especially on large datasets.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Using tax_query to retrieve a list of posts">
+        <code title="Valid: No potentially slow query keys.">
         <![CDATA[
-$query = new WP_Query(
-    array(
-        'tax_query' => array(
-            array(
-                'taxonomy' => 'color',
-                'field'    => 'slug',
-                'terms'    => array(
-                    'blue',
-                    'red',
-                )
-            )
-        )
-    )
+$args = array(
+    'post_type' => 'post',
 );
-        ]]>
-        </code>
-        <code title="Invalid: Using meta_query to retrieve a list of posts">
-        <![CDATA[
-$query = new WP_Query(
-    array(
-        'meta_query' => array(
-            array(
-                'key'     => 'color',
-                'compare' => 'IN',
-                'value'   => array(
-                    'blue',
-                    'red',
-                )
-            )
-        )
-    )
-);
-        ]]>
-        </code>
-    </code_comparison>
-    <code_comparison>
-        <code title="Valid: in case of binary metadata (true/false) check if meta_key exist and remove it otherwise">
-        <![CDATA[
-// mark post 123 as "featured"
-update_post_meta( 123, 'is_featured', true );
 
-// remove "featured" state for post 456
-delete_post_meta( 456, 'is_featured' );
 
-$query = new WP_Query(
-    array(
-        'meta_key' => 'is_featured'
-    ),
-);
+$query = 'post_type=post&orderby=date';
         ]]>
         </code>
-        <code title="Invalid: check for the value of a binary metadata, which is slower">
+        <code title="Invalid: Using potentially slow query keys.">
         <![CDATA[
-// mark post 123 as "featured"
-update_post_meta( 123, 'is_featured', true );
-
-// mark post 456 as not "featured"
-update_post_meta( 456, 'is_featured', false );
-
-$query = new WP_Query(
-    array(
-        'meta_key' => 'is_featured',
-        'meta_value' => true
-    ),
+$args = array(
+    '<em>meta_key</em>'   => 'color',
+    '<em>meta_value</em>' => 'blue',
 );
+
+$query = 'post_type=post&<em>meta_key</em>=featured';
         ]]>
         </code>
     </code_comparison>

From 63ff8ec1334f36981ea91ae2382b8dd56bf952fe Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Thu, 26 Feb 2026 08:01:26 -0300
Subject: [PATCH 3/4] Apply suggestions from code review

Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
 WordPress/Docs/DB/SlowDBQueryStandard.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/WordPress/Docs/DB/SlowDBQueryStandard.xml b/WordPress/Docs/DB/SlowDBQueryStandard.xml
index 79d10e4b95..789e11bc7a 100644
--- a/WordPress/Docs/DB/SlowDBQueryStandard.xml
+++ b/WordPress/Docs/DB/SlowDBQueryStandard.xml
@@ -11,9 +11,9 @@
     <code_comparison>
         <code title="Valid: No potentially slow query keys.">
         <![CDATA[
-$args = array(
+$query = new WP_Query( array(
     'post_type' => 'post',
-);
+) );
 
 
 $query = 'post_type=post&orderby=date';
@@ -21,10 +21,10 @@ $query = 'post_type=post&orderby=date';
         </code>
         <code title="Invalid: Using potentially slow query keys.">
         <![CDATA[
-$args = array(
+$query = new WP_Query( array(
     '<em>meta_key</em>'   => 'color',
     '<em>meta_value</em>' => 'blue',
-);
+) );
 
 $query = 'post_type=post&<em>meta_key</em>=featured';
         ]]>

From 4e8f54cc055d7672e764894cd0552daad30fb25d Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Thu, 5 Mar 2026 09:58:10 -0300
Subject: [PATCH 4/4] Use different variable name for query string examples

---
 WordPress/Docs/DB/SlowDBQueryStandard.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/WordPress/Docs/DB/SlowDBQueryStandard.xml b/WordPress/Docs/DB/SlowDBQueryStandard.xml
index 789e11bc7a..230c7fafb6 100644
--- a/WordPress/Docs/DB/SlowDBQueryStandard.xml
+++ b/WordPress/Docs/DB/SlowDBQueryStandard.xml
@@ -16,7 +16,7 @@ $query = new WP_Query( array(
 ) );
 
 
-$query = 'post_type=post&orderby=date';
+$args = 'post_type=post&orderby=date';
         ]]>
         </code>
         <code title="Invalid: Using potentially slow query keys.">
@@ -26,7 +26,7 @@ $query = new WP_Query( array(
     '<em>meta_value</em>' => 'blue',
 ) );
 
-$query = 'post_type=post&<em>meta_key</em>=featured';
+$args = 'post_type=post&<em>meta_key</em>=featured';
         ]]>
         </code>
     </code_comparison>