From 547b7ab3affb295cbe12fda348d0ef7fb745fc39 Mon Sep 17 00:00:00 2001
From: Paul Wong-Gibbs <djpaul@gmail.com>
Date: Thu, 13 Jun 2024 12:17:00 +0200
Subject: [PATCH] Add documentation for WordPress.DB.RestrictedClasses

Co-authored-by: Paul Wong-Gibbs <paulgibbs@users.noreply.github.com>
Co-authored-by: Rodrigo Primo <rodrigoprimo@users.noreply.github.com>
Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
 .../Docs/DB/RestrictedClassesStandard.xml     | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 WordPress/Docs/DB/RestrictedClassesStandard.xml

diff --git a/WordPress/Docs/DB/RestrictedClassesStandard.xml b/WordPress/Docs/DB/RestrictedClassesStandard.xml
new file mode 100644
index 0000000000..36094d6b9c
--- /dev/null
+++ b/WordPress/Docs/DB/RestrictedClassesStandard.xml
@@ -0,0 +1,66 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Restricted Database Classes"
+    >
+    <standard>
+    <![CDATA[
+    Avoid touching the database directly. Use the $wpdb object and associated functions instead of using classes from PHP database extensions.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using a WordPress function to fetch posts.">
+        <![CDATA[
+$results = <em>get_posts()</em>;
+        ]]>
+        </code>
+        <code title="Invalid: Using the mysqli class to fetch posts.">
+        <![CDATA[
+$mysqli = <em>new mysqli</em>(
+    'localhost',
+    $user,
+    $pass,
+    $db
+);
+
+$results = $mysqli->query(
+    "SELECT * FROM wp_posts LIMIT 5"
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <code_comparison>
+        <code title="Valid: Using WordPress functions to insert a post.">
+        <![CDATA[
+<em>wp_insert_post</em>(
+    array( 'post_title' => 'Title' )
+);
+
+// or...
+
+global $wpdb;
+<em>$wpdb->insert</em>(
+    $wpdb->posts,
+    array( 'post_title' => 'Title' ),
+    array( '%s' )
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using PDO class to insert a post.">
+        <![CDATA[
+$pdo = <em>new PDO</em>(
+    $dsn,
+    $user,
+    $pass
+);
+
+$stmt = $pdo->prepare(
+    "INSERT INTO wp_posts (post_title)
+    VALUES (?)"
+);
+
+$stmt->execute( array( 'Title' ) );
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>