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

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

diff --git a/WordPress/Docs/DB/PreparedSQLStandard.xml b/WordPress/Docs/DB/PreparedSQLStandard.xml
new file mode 100644
index 0000000000..d4c63db285
--- /dev/null
+++ b/WordPress/Docs/DB/PreparedSQLStandard.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Prepared SQL"
+    >
+    <standard>
+    <![CDATA[
+    When making direct database queries using $wpdb, you should use $wpdb->prepare(), and use placeholders for all variables used in the query. You should not use variable interpolation or concatenation.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Placeholders with $wpdb->prepare() used for all variables in query.">
+        <![CDATA[
+$val = $_GET['foo'];
+$wpdb->prepare(
+    "SELECT * from table WHERE field = %s",
+    $val
+);
+        ]]>
+        </code>
+        <code title="Invalid: Interpolated variables used in $wpdb->prepare().">
+        <![CDATA[
+$val = $_GET['foo'];
+$wpdb->prepare(
+    "SELECT * from table WHERE field = {$val}"
+);
+        ]]>
+        </code>
+    </code_comparison>
+
+    <code_comparison>
+        <code title="Valid: Placeholders with $wpdb->prepare() used for all variables in query.">
+        <![CDATA[
+$val = $_GET['foo'];
+$wpdb->prepare(
+    "SELECT * from table WHERE field = %s",
+    $val
+);
+        ]]>
+        </code>
+        <code title="Invalid: Concatenation of variables used in $wpdb->prepare().">
+        <![CDATA[
+$val = $_GET['foo'];
+$wpdb->prepare(
+    "SELECT * from table WHERE field = " . $val
+);
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>