From c9c7a49ee8ce516b5164daace0233b7aa6cf25ab Mon Sep 17 00:00:00 2001
From: gogdzl <diego.rodrigues@automattic.com>
Date: Tue, 17 Sep 2024 16:38:53 -0700
Subject: [PATCH 1/5] 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 0000000000..9807cd4c1e
--- /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>

From 8c47d857133b5101f2cf52834a775344fedecd43 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Wed, 4 Feb 2026 10:49:11 -0300
Subject: [PATCH 2/5] Apply changes suggested during PR review

- Fix the title to match the sniff name.
- Be specific about the @ operator in the standard description.
- Mention the exception for certain functions without listing them.
- Simplify the code examples to focus on the presence/absence of @.
- Rename the variable from $conn_id to $connection as
`ftp_connect()` does not return a connection ID.
---
 .../Docs/PHP/NoSilencedErrorsStandard.xml     | 25 +++++--------------
 1 file changed, 6 insertions(+), 19 deletions(-)

diff --git a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
index 9807cd4c1e..910a55790d 100644
--- a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
+++ b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
@@ -1,35 +1,22 @@
 <?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"
+    title="No Silenced Errors"
     >
     <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()`
+    The error silencing operator (@) should not be used. As an exception, the operator is allowed for certain functions where errors cannot be prevented through error checking.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Using proper error checking when calling functions not in the allowed list.">
+        <code title="Valid: Calling a function without error silencing.">
         <![CDATA[
-$conn_id = ftp_connect( $ftp_server );
-if ( ! $conn_id ) {
-  // Handle it as needed.
-}
+$connection = <em></em>ftp_connect( $ftp_server );
         ]]>
         </code>
-        <code title="Invalid: Using the error operator to silence errors.">
+        <code title="Invalid: Using the @ operator to silence errors.">
         <![CDATA[
-$conn_id = <em>@ftp_connect( $ftp_server );</em>
+$connection = <em>@</em>ftp_connect( $ftp_server );
         ]]>
         </code>
     </code_comparison>

From 5f150d4c802ae99395c45486502a7c2cec723d11 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 6 Feb 2026 15:12:24 -0300
Subject: [PATCH 3/5] Explain why in the standard description

Following the suggestion in PR 2687, improve the standard
description to explain why the error silencing operator should
not be used instead of just repeating the rule.
---
 WordPress/Docs/PHP/NoSilencedErrorsStandard.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
index 910a55790d..a0e1749adc 100644
--- a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
+++ b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
@@ -5,7 +5,9 @@
     >
     <standard>
     <![CDATA[
-    The error silencing operator (@) should not be used. As an exception, the operator is allowed for certain functions where errors cannot be prevented through error checking.
+    The error silencing operator (@) should not be used. It suppresses errors instead of handling them properly, making debugging more difficult.
+
+    As an exception, the operator is allowed for certain functions where errors cannot be prevented through error checking.
     ]]>
     </standard>
     <code_comparison>

From 019e0bbf05ecb6b7abd891c96d2a71ac08766175 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Mon, 23 Feb 2026 15:48:29 -0300
Subject: [PATCH 4/5] Apply suggestions from code review

Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
 WordPress/Docs/PHP/NoSilencedErrorsStandard.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
index a0e1749adc..9ffeba96dc 100644
--- a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
+++ b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
@@ -5,18 +5,18 @@
     >
     <standard>
     <![CDATA[
-    The error silencing operator (@) should not be used. It suppresses errors instead of handling them properly, making debugging more difficult.
+    The error silencing operator (@) should not be used. Errors should be addressed through proper checking rather than being silenced.
 
-    As an exception, the operator is allowed for certain functions where errors cannot be prevented through error checking.
+    As an exception, the operator is allowed for certain functions where warnings cannot be prevented through error checking.
     ]]>
     </standard>
     <code_comparison>
         <code title="Valid: Calling a function without error silencing.">
         <![CDATA[
-$connection = <em></em>ftp_connect( $ftp_server );
+$connection = <em>ftp_connect</em>( $ftp_server );
         ]]>
         </code>
-        <code title="Invalid: Using the @ operator to silence errors.">
+        <code title="Invalid: Using the @ operator to silence warnings and errors.">
         <![CDATA[
 $connection = <em>@</em>ftp_connect( $ftp_server );
         ]]>

From 66adedad84af7a57afa692e1be3011360cb53af7 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 24 Feb 2026 12:04:28 -0300
Subject: [PATCH 5/5] Improve description and code samples based on PR review
 discussion

---
 WordPress/Docs/PHP/NoSilencedErrorsStandard.xml | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
index 9ffeba96dc..9db8f6e942 100644
--- a/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
+++ b/WordPress/Docs/PHP/NoSilencedErrorsStandard.xml
@@ -5,20 +5,24 @@
     >
     <standard>
     <![CDATA[
-    The error silencing operator (@) should not be used. Errors should be addressed through proper checking rather than being silenced.
+    The error silencing operator (@) should not be used. In the vast majority of cases, there is no need for the error silencing operator if the parameters passed to a function are checked ahead of the call.
 
-    As an exception, the operator is allowed for certain functions where warnings cannot be prevented through error checking.
+    As an exception, the operator is allowed for certain functions where warnings cannot be prevented.
     ]]>
     </standard>
     <code_comparison>
         <code title="Valid: Calling a function without error silencing.">
         <![CDATA[
-$connection = <em>ftp_connect</em>( $ftp_server );
+if ( isset( $replace_pairs[''] ) ) {
+    unset( $replace_pairs[''] );
+}
+
+$result = <em></em>strtr( $str, $replace_pairs );
         ]]>
         </code>
-        <code title="Invalid: Using the @ operator to silence warnings and errors.">
+        <code title="Invalid: Using the @ operator to silence warnings.">
         <![CDATA[
-$connection = <em>@</em>ftp_connect( $ftp_server );
+$result = <em>@</em>strtr( $str, $replace_pairs );
         ]]>
         </code>
     </code_comparison>