From 32fe3c4b62d54aa4e82d03d71979685a2bd2e677 Mon Sep 17 00:00:00 2001
From: Jay McPartland <2131911+jaymcp@users.noreply.github.com>
Date: Tue, 23 Jul 2024 10:37:46 +0100
Subject: [PATCH] [Documentation]: WordPress.DB.PreparedSQL (#2454)

* Docs: add documentation for WordPress.DB.PreparedSQL

---------

Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
 WordPress/Docs/DB/PreparedSQLStandard.xml | 51 +++++++++++++++++++++++
 1 file changed, 51 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 000000000..d58d61769
--- /dev/null
+++ b/WordPress/Docs/DB/PreparedSQLStandard.xml
@@ -0,0 +1,51 @@
+<?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 querying the database, you should use $wpdb->prepare() to escape and quote the contents of variables. This prevents SQL injection.
+    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[
+$wpdb->prepare(
+    'SELECT * from table
+        WHERE field = <em>%s</em>',
+    <em>$_GET['foo']</em>
+);
+        ]]>
+        </code>
+        <code title="Invalid: Interpolated variables used in $wpdb->query().">
+        <![CDATA[
+$wpdb->query(
+    "SELECT * from table
+    WHERE field = <em>{$_GET['foo']}</em>"
+);
+        ]]>
+        </code>
+    </code_comparison>
+
+    <code_comparison>
+        <code title="Valid: Placeholders with $wpdb->prepare() used for all variables in query.">
+        <![CDATA[
+$wpdb->prepare(
+    'SELECT * from table
+        WHERE field = <em>%s</em>',
+    <em>$value</em>
+);
+        ]]>
+        </code>
+        <code title="Invalid: Concatenation of variables used in $wpdb->*().">
+        <![CDATA[
+$wpdb->get_results(
+    "SELECT * from table
+    WHERE field = <em>" . $value</em>
+);
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>