From 19fb4e272729ccbbe2708bf302923ef6bb3335c0 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 23 Nov 2025 05:09:18 +0100
Subject: [PATCH] PHPCS/PHPCompatibility: favour inline ignores over blanket
 rule excludes

Best practice tweak regarding the use of PHPCompatibility.

It is strongly recommended to use inline ignore annotations when a reported issue is not a problem (because it is accompanied by a `function_exists()`, `defined()` or other check), instead of excluding a rule completely via the ruleset.

Blanket code-base wide ignores mean that:
* ... if a PR introduces new code (or changes existing code) which uses a non-cross-version compatible PHP feature...
* ... and the code doesn't have the right safeguards in place for cross-version compatibility...
* ... PHPCompatibility would not flag it because of the codebase wide ignore...
* ... which could cause problems for the end-users.

Selective, inline ignores ensure that only the annotated error is ignored and only for that specific bit of code, preventing the above described problem.

It also means that when something changes in PHP - like a deprecated method being removed -, you will be notified about the issue again so you can review if the current cross-version compatibility tweak is still the most optimal one.
---
 phpcs.xml.dist    | 9 +--------
 src/PHPMailer.php | 4 ++++
 src/SMTP.php      | 2 ++
 3 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index 5642fd91..bf51a72c 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -27,14 +27,7 @@
         <exclude name="PSR2.Methods.MethodDeclaration.Underscore"/>
         <exclude name="PSR12.Properties.ConstantVisibility.NotFound"/>
     </rule>
-    <rule ref="PHPCompatibility">
-        <exclude name="PHPCompatibility.Constants.NewConstants.stream_crypto_method_tlsv1_1_clientFound"/>
-        <exclude name="PHPCompatibility.Constants.NewConstants.stream_crypto_method_tlsv1_2_clientFound"/>
-        <exclude name="PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003DeprecatedRemoved"/>
-        <exclude name="PHPCompatibility.FunctionUse.NewFunctions.random_bytesFound"/>
-        <exclude name="PHPCompatibility.IniDirectives.RemovedIniDirectives.mbstring_func_overloadDeprecatedRemoved"/>
-        <exclude name="PHPCompatibility.ParameterValues.NewIDNVariantDefault.NotSet"/>
-    </rule>
+    <rule ref="PHPCompatibility"/>
 
 
     <!--
diff --git a/src/PHPMailer.php b/src/PHPMailer.php
index 91512c43..f37eab7d 100644
--- a/src/PHPMailer.php
+++ b/src/PHPMailer.php
@@ -876,6 +876,7 @@ class PHPMailer
     private function mailPassthru($to, $subject, $body, $header, $params)
     {
         //Check overloading of mail function to avoid double-encoding
+        // phpcs:ignore PHPCompatibility.IniDirectives.RemovedIniDirectives.mbstring_func_overloadDeprecatedRemoved
         if ((int)ini_get('mbstring.func_overload') & 1) {
             $subject = $this->secureHeader($subject);
         } else {
@@ -1585,9 +1586,11 @@ class PHPMailer
                     );
                 } elseif (defined('INTL_IDNA_VARIANT_2003')) {
                     //Fall back to this old, deprecated/removed encoding
+                    // phpcs:ignore PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003DeprecatedRemoved
                     $punycode = idn_to_ascii($domain, $errorcode, \INTL_IDNA_VARIANT_2003);
                 } else {
                     //Fall back to a default we don't know about
+                    // phpcs:ignore PHPCompatibility.ParameterValues.NewIDNVariantDefault.NotSet
                     $punycode = idn_to_ascii($domain, $errorcode);
                 }
                 if (false !== $punycode) {
@@ -2958,6 +2961,7 @@ class PHPMailer
         $bytes = '';
         if (function_exists('random_bytes')) {
             try {
+                // phpcs:ignore PHPCompatibility.FunctionUse.NewFunctions.random_bytesFound -- Wrapped in function_exists.
                 $bytes = random_bytes($len);
             } catch (\Exception $e) {
                 //Do nothing
diff --git a/src/SMTP.php b/src/SMTP.php
index 9bf6135a..c3fb54cb 100644
--- a/src/SMTP.php
+++ b/src/SMTP.php
@@ -494,7 +494,9 @@ class SMTP
         //PHP 5.6.7 dropped inclusion of TLS 1.1 and 1.2 in STREAM_CRYPTO_METHOD_TLS_CLIENT
         //so add them back in manually if we can
         if (defined('STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT')) {
+            // phpcs:ignore PHPCompatibility.Constants.NewConstants.stream_crypto_method_tlsv1_2_clientFound
             $crypto_method |= STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT;
+            // phpcs:ignore PHPCompatibility.Constants.NewConstants.stream_crypto_method_tlsv1_1_clientFound
             $crypto_method |= STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT;
         }