From 6c9530bc88218de4d1901eb6796faad049a796bd Mon Sep 17 00:00:00 2001
From: Jay McPartland <jay@bigbite.net>
Date: Thu, 13 Jun 2024 15:52:53 +0200
Subject: [PATCH] docs: add documentation for WordPress.DB.DirectDatabaseQuery

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

diff --git a/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
new file mode 100644
index 0000000000..c1312e7fc8
--- /dev/null
+++ b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
@@ -0,0 +1,119 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Direct Database Query"
+    >
+    <standard>
+    <![CDATA[
+    You should not make direct database queries, but instead use abstractions such as WP_Query.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using WP_Query to retrieve data.">
+        <![CDATA[
+$my_query = new WP_Query(
+    [
+        'post_type' => 'foo',
+    ]
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using a direct query to retrieve data.">
+        <![CDATA[
+$results = $wpdb->get_results(
+    $wpdb->prepare(
+        "SELECT * FROM x WHERE y = %s",
+        'foo',
+    ),
+);
+        ]]>
+        </code>
+    </code_comparison>
+
+    <standard>
+    <![CDATA[
+    You should not make direct database queries without caching.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: The results of a direct database query are stored in the object cache.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+    
+    $cached = wp_cache_get( 'foo' );
+    if ( false !== $cached ) {
+        return $cached;
+    }
+
+    $results = $wpdb->query(
+        'SELECT x FROM foo'
+    );
+
+    wp_cache_set( 'foo', $results );
+    return $results;
+}
+        ]]>
+        </code>
+        <code title="Invalid: Direct database query is made without leveraging the object cache.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+    return $wpdb->query( 'SELECT x FROM foo' );
+}
+        ]]>
+        </code>
+    </code_comparison>
+    <code_comparison>
+        <code title="Valid: The results of a direct database query are stored in the object cache.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+
+    $cached = wp_cache_get( 'foo' );
+    if ( false !== $cached ) {
+        return $cached;
+    }
+
+    $results = $wpdb->query(
+        'SELECT x FROM foo'
+    );
+
+    wp_cache_set( 'foo', $results );
+    return $results;
+}
+        ]]>
+        </code>
+        <code title="Invalid: Incorrect implementation of caching with a direct database query.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+    $results = $wpdb->query(
+        'SELECT * from foo'
+    );
+
+    wp_cache_set( 'foo', $results );
+    return $results;
+}
+        ]]>
+        </code>
+    </code_comparison>
+
+    <standard>
+    <![CDATA[
+    You should not make direct database queries to alter the database schema.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Altering database schema using the dbDelta function.">
+        <![CDATA[
+dbDelta( 'CREATE TABLE foo' );
+        ]]>
+        </code>
+        <code title="Invalid: Altering database schema using a direct database query.">
+        <![CDATA[
+$wpdb->query( 'CREATE TABLE foo' );
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>