From e24f650f24fb100646e6e50fc8f1a5f6701ca809 Mon Sep 17 00:00:00 2001
From: gogdzl <diego.rodrigues@automattic.com>
Date: Tue, 17 Sep 2024 16:38:53 -0700
Subject: [PATCH] Add documentation for WordPress.PHP.NoSilencedErrors

---
 .../Docs/PHP/NoSilencedErrorsStandard.xml     | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 WordPress/Docs/PHP/NoSilencedErrorsStandard.xml

diff --git a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
new file mode 100644
index 000000000..9807cd4c1
--- /dev/null
+++ b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Discourage the use of the PHP error silencing operator"
+    >
+    <standard>
+    <![CDATA[
+    Silencing errors is strongly discouraged. Use proper error checking instead.
+
+    Using the error operator with certain functions is allowed because no amount of error checking can fully prevent PHP from throwing errors when these functions are executed. The functions where this is permitted include, but are not limited to:
+
+    - `file_exists()`
+    - `file_get_contents()`
+    - `filesize()`
+    - `filetype()`
+    - `fopen()`
+    - `ftp_login()`
+    - `ftp_rename()`
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using proper error checking when calling functions not in the allowed list.">
+        <![CDATA[
+$conn_id = ftp_connect( $ftp_server );
+if ( ! $conn_id ) {
+  // Handle it as needed.
+}
+        ]]>
+        </code>
+        <code title="Invalid: Using the error operator to silence errors.">
+        <![CDATA[
+$conn_id = <em>@ftp_connect( $ftp_server );</em>
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>