From 051b81791f937c4efc1045567b06b52025a2306f Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 23 Nov 2025 04:34:20 +0100
Subject: [PATCH 1/7] CS: start using PHPCompatibility 10

Long anticipated, finally here: PHPCompatibility 10.0.0-alpha1 :tada:

PHPCompatibility 10.0.0 brings huge improvements in both what is being detected (> 50 new sniffs), as well as the detection accuracy for pre-existing sniffs.

Even though still "unstable", it is stable enough for our purposes and the advantages of using it outweigh the disadvantage of it being an unstable version. By setting the `minimum-stability` and `prefer-stable` settings in the `composer.json`, we can ensure that we don't get the `dev-develop` branch, but rather get a `10.0.0` tag, unstable or not.

Includes updating the PHPCS version constraints to match.
Includes updating the exclusions in the ruleset for changes in the error codes due to further changes in PHP having been made (and now being detected).

Ref:
* https://github.com/PHPCompatibility/PHPCompatibility/wiki/Upgrading-to-PHPCompatibility-10.0
* https://github.com/PHPCompatibility/PHPCompatibility/releases/tag/10.0.0-alpha1
---
 composer.json  | 6 ++++--
 phpcs.xml.dist | 4 ++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/composer.json b/composer.json
index 05b05c75..6af16647 100644
--- a/composer.json
+++ b/composer.json
@@ -42,8 +42,8 @@
         "doctrine/annotations": "^1.2.6 || ^1.13.3",
         "php-parallel-lint/php-console-highlighter": "^1.0.0",
         "php-parallel-lint/php-parallel-lint": "^1.3.2",
-        "phpcompatibility/php-compatibility": "^9.3.5",
-        "squizlabs/php_codesniffer": "^3.7.2",
+        "phpcompatibility/php-compatibility": "^10.0.0@dev",
+        "squizlabs/php_codesniffer": "^3.13.5",
         "yoast/phpunit-polyfills": "^1.0.4"
     },
     "suggest": {
@@ -58,6 +58,8 @@
         "symfony/polyfill-mbstring": "To support UTF-8 if the Mbstring PHP extension is not enabled (^1.2)",
         "thenetworg/oauth2-azure": "Needed for Microsoft XOAUTH2 authentication"
     },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
     "autoload": {
         "psr-4": {
             "PHPMailer\\PHPMailer\\": "src/"
diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index e2d1e5c6..5642fd91 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -30,9 +30,9 @@
     <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_2003Deprecated"/>
+        <exclude name="PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003DeprecatedRemoved"/>
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.random_bytesFound"/>
-        <exclude name="PHPCompatibility.IniDirectives.RemovedIniDirectives.mbstring_func_overloadDeprecated"/>
+        <exclude name="PHPCompatibility.IniDirectives.RemovedIniDirectives.mbstring_func_overloadDeprecatedRemoved"/>
         <exclude name="PHPCompatibility.ParameterValues.NewIDNVariantDefault.NotSet"/>
     </rule>
 

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 2/7] 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;
         }
 

From c24a4147cd07c6c067174a92dec092b72eb9865a Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 23 Nov 2025 05:11:45 +0100
Subject: [PATCH 3/7] PHPCS: add a few more selective ignores

... for things already handled correctly in the code.
---
 src/PHPMailer.php                                    | 4 ++++
 test/Fixtures/LocalizationTest/phpmailer.lang-yz.php | 2 ++
 2 files changed, 6 insertions(+)

diff --git a/src/PHPMailer.php b/src/PHPMailer.php
index f37eab7d..bd9825f3 100644
--- a/src/PHPMailer.php
+++ b/src/PHPMailer.php
@@ -1258,8 +1258,10 @@ class PHPMailer
         $addresses = [];
         if (function_exists('imap_rfc822_parse_adrlist')) {
             //Use this built-in parser if it's available
+            // phpcs:ignore PHPCompatibility.FunctionUse.RemovedFunctions.imap_rfc822_parse_adrlistRemoved -- wrapped in function_exists()
             $list = imap_rfc822_parse_adrlist($addrstr, '');
             // Clear any potential IMAP errors to get rid of notices being thrown at end of script.
+            // phpcs:ignore PHPCompatibility.FunctionUse.RemovedFunctions.imap_errorsRemoved -- wrapped in function_exists()
             imap_errors();
             foreach ($list as $address) {
                 if (
@@ -5117,12 +5119,14 @@ class PHPMailer
         }
         if (openssl_sign($signHeader, $signature, $privKey, 'sha256WithRSAEncryption')) {
             if (\PHP_MAJOR_VERSION < 8) {
+                // phpcs:ignore PHPCompatibility.FunctionUse.RemovedFunctions.openssl_pkey_freeDeprecated
                 openssl_pkey_free($privKey);
             }
 
             return base64_encode($signature);
         }
         if (\PHP_MAJOR_VERSION < 8) {
+            // phpcs:ignore PHPCompatibility.FunctionUse.RemovedFunctions.openssl_pkey_freeDeprecated
             openssl_pkey_free($privKey);
         }
 
diff --git a/test/Fixtures/LocalizationTest/phpmailer.lang-yz.php b/test/Fixtures/LocalizationTest/phpmailer.lang-yz.php
index 2b0f8aa3..1d190b4b 100644
--- a/test/Fixtures/LocalizationTest/phpmailer.lang-yz.php
+++ b/test/Fixtures/LocalizationTest/phpmailer.lang-yz.php
@@ -8,6 +8,8 @@
  * Note: this test fixture uses a syntax (backticks) which has been deprecated in PHP 8.5 and
  * is slated for removal in PHP 9.0.
  * For that reason, the file is excluded from the linting check on PHP 8.5 and above.
+ *
+ * @phpcs:disable PHPCompatibility.LanguageConstructs.RemovedLanguageConstructs.t_backtickDeprecated
  */
 
 $PHPMAILER_LANG['extension_missing'] = 'Confirming that test fixture was loaded correctly (yz).';

From b9d0e242fbdfdd2c9139e156ee44d6f859cbbd53 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 23 Nov 2025 05:14:13 +0100
Subject: [PATCH 4/7] Examples/mailing_list: remove use of `E_STRICT`

While this is only example code, it is still code which should be functional for all supported PHP versions.

As `E_STRICT` has been deprecated since PHP 8.4 and wasn't really all that useful since PHP 7.0 anyway, it's probably better not to mention it in the example code.

Ref: https://wiki.php.net/rfc/deprecations_php_8_4#remove_e_strict_error_level_and_deprecate_e_strict_constant
---
 examples/mailing_list.phps | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/mailing_list.phps b/examples/mailing_list.phps
index 4a536e7c..a3aa9d4d 100644
--- a/examples/mailing_list.phps
+++ b/examples/mailing_list.phps
@@ -8,7 +8,7 @@
 use PHPMailer\PHPMailer\PHPMailer;
 use PHPMailer\PHPMailer\Exception;
 
-error_reporting(E_STRICT | E_ALL);
+error_reporting(E_ALL);
 
 date_default_timezone_set('Etc/UTC');
 

From 57ef8c914f78741e359f0cffe679d87c6ce46ccc Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 24 Nov 2025 10:48:09 +0100
Subject: [PATCH 5/7] Escape special characters the same way in all PHP
 versions

The `htmlspecialchars()` function is used to escape arbitrary text strings for display.

Original the default for the `$flags` parameter of that function in PHP was `ENT_COMPAT`, which translates to "convert double quotes to `&quot;` and leave single quotes alone".

As of PHP 8.1, the default value for the `$flags` parameter has been made more robust and was changed to `ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401`, which translates to "convert both double and single quotes, replace invalid code unit sequences with a Unicode Replacement Character and treat code as HTML 4.01".

For code to provide the same/predictable output cross-version PHP, the `$flags` parameter should be explicitly set and what with the new default value being the more robust one, this commit adds that value for `$flags` in all instances of function calls to `htmlspecialchars()`.

Once the application minimum PHP version is PHP 8.1 or higher, the parameter can be removed again (as the value will then be the same as the default parameter value).

Ref: https://www.php.net/manual/en/function.htmlspecialchars.php
---
 examples/mailing_list.phps              | 18 ++++++++++++++----
 examples/send_file_upload.phps          |  2 +-
 examples/send_multiple_file_upload.phps |  2 +-
 get_oauth_token.php                     |  2 +-
 4 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/examples/mailing_list.phps b/examples/mailing_list.phps
index a3aa9d4d..9eb05d63 100644
--- a/examples/mailing_list.phps
+++ b/examples/mailing_list.phps
@@ -51,7 +51,10 @@ foreach ($result as $row) {
     try {
         $mail->addAddress($row['email'], $row['full_name']);
     } catch (Exception $e) {
-        echo 'Invalid address skipped: ' . htmlspecialchars($row['email']) . '<br>';
+        printf(
+            'Invalid address skipped: %s<br>',
+            htmlspecialchars($row['email'], ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401)
+        );
         continue;
     }
     if (!empty($row['photo'])) {
@@ -66,8 +69,11 @@ foreach ($result as $row) {
 
     try {
         $mail->send();
-        echo 'Message sent to :' . htmlspecialchars($row['full_name']) . ' (' .
-            htmlspecialchars($row['email']) . ')<br>';
+        printf(
+            'Message sent to : %s (%s)<br>',
+            htmlspecialchars($row['full_name'], ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401),
+            htmlspecialchars($row['email'], ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401)
+        );
         //Mark it as sent in the DB
         mysqli_query(
             $mysql,
@@ -75,7 +81,11 @@ foreach ($result as $row) {
             mysqli_real_escape_string($mysql, $row['email']) . "'"
         );
     } catch (Exception $e) {
-        echo 'Mailer Error (' . htmlspecialchars($row['email']) . ') ' . $mail->ErrorInfo . '<br>';
+        printf(
+            'Mailer Error (%s) %s<br>',
+            htmlspecialchars($row['email'], ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401),
+            $mail->ErrorInfo
+        );
         //Reset the connection to abort sending this message
         //The loop will continue trying to send to the rest of the list
         $mail->getSMTPInstance()->reset();
diff --git a/examples/send_file_upload.phps b/examples/send_file_upload.phps
index 31d22837..8c6ec070 100644
--- a/examples/send_file_upload.phps
+++ b/examples/send_file_upload.phps
@@ -54,7 +54,7 @@ if (array_key_exists('userfile', $_FILES)) {
         <input type="submit" value="Send File">
     </form>
 <?php } else {
-    echo htmlspecialchars($msg);
+    echo htmlspecialchars($msg, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401);
 } ?>
 </body>
 </html>
diff --git a/examples/send_multiple_file_upload.phps b/examples/send_multiple_file_upload.phps
index aeb65c14..e892ecb5 100644
--- a/examples/send_multiple_file_upload.phps
+++ b/examples/send_multiple_file_upload.phps
@@ -54,7 +54,7 @@ if (array_key_exists('userfile', $_FILES)) {
         <input type="submit" value="Send Files">
     </form>
 <?php } else {
-    echo htmlspecialchars($msg);
+    echo htmlspecialchars($msg, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401);
 } ?>
 </body>
 </html>
diff --git a/get_oauth_token.php b/get_oauth_token.php
index 0e54a00b..9342b9c7 100644
--- a/get_oauth_token.php
+++ b/get_oauth_token.php
@@ -178,5 +178,5 @@ if (!isset($_GET['code'])) {
     );
     //Use this to interact with an API on the users behalf
     //Use this to get a new access token if the old one expires
-    echo 'Refresh Token: ', htmlspecialchars($token->getRefreshToken());
+    echo 'Refresh Token: ', htmlspecialchars($token->getRefreshToken(), ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401);
 }

From 381c209df196365f0fd863bff30d251f4101558a Mon Sep 17 00:00:00 2001
From: Marcus Bointon <marcus@synchromedia.co.uk>
Date: Mon, 24 Nov 2025 18:12:56 +0100
Subject: [PATCH 6/7] Switch away from the IMAP functions, suggest using an
 IMAP library instead, and update the example to do that

---
 composer.json       |  3 ++-
 examples/gmail.phps | 30 +++++++++++++++---------------
 2 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/composer.json b/composer.json
index 6af16647..63d0ffd6 100644
--- a/composer.json
+++ b/composer.json
@@ -56,7 +56,8 @@
         "league/oauth2-google": "Needed for Google XOAUTH2 authentication",
         "psr/log": "For optional PSR-3 debug logging",
         "symfony/polyfill-mbstring": "To support UTF-8 if the Mbstring PHP extension is not enabled (^1.2)",
-        "thenetworg/oauth2-azure": "Needed for Microsoft XOAUTH2 authentication"
+        "thenetworg/oauth2-azure": "Needed for Microsoft XOAUTH2 authentication",
+        "directorytree/imapengine": "For uploading sent messages via IMAP, see gmail example"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,
diff --git a/examples/gmail.phps b/examples/gmail.phps
index fe6e09a9..25e18a48 100644
--- a/examples/gmail.phps
+++ b/examples/gmail.phps
@@ -83,26 +83,26 @@ if (!$mail->send()) {
     echo 'Message sent!';
     //Section 2: IMAP
     //Uncomment these to save your message in the 'Sent Mail' folder.
-    #if (save_mail($mail)) {
+    #if (save_mail($mail->getSentMIMEMessage())) {
     #    echo "Message saved!";
     #}
 }
 
 //Section 2: IMAP
-//IMAP commands requires the PHP IMAP Extension, found at: https://php.net/manual/en/imap.setup.php
-//Function to call which uses the PHP imap_*() functions to save messages: https://php.net/manual/en/book.imap.php
-//You can use imap_getmailboxes($imapStream, '/imap/ssl', '*' ) to get a list of available folders or labels, this can
-//be useful if you are trying to get this working on a non-Gmail IMAP server.
-function save_mail($mail)
-{
-    //You can change 'Sent Mail' to any other folder or tag
-    $path = '{imap.gmail.com:993/imap/ssl}[Gmail]/Sent Mail';
+//This example uses the directorytree/imapengine IMAP library: https://imapengine.com
+//Earlier versions of this code used the deprecated PHP imap_* functions.
+function save_mail($message) {
+    $mailbox = new \DirectoryTree\ImapEngine\Mailbox([
+        'host' => 'imap.gmail.com',
+        'port' => 993,
+        'encryption' => 'ssl',
+        'username' => 'user@example.com',
+        'password' => 'password',
+    ]);
 
-    //Tell your server to open an IMAP connection using the same username and password as you used for SMTP
-    $imapStream = imap_open($path, $mail->Username, $mail->Password);
+    // Find the "sent" messages folder – yours may have a different name.
+    $folder = $mailbox->folders()->find('Sent Mail');
 
-    $result = imap_append($imapStream, $path, $mail->getSentMIMEMessage());
-    imap_close($imapStream);
-
-    return $result;
+    $folder->messages()->append($message);
+    return true;
 }

From 12494b183059a966fdfb74e778311d041b690c8a Mon Sep 17 00:00:00 2001
From: Marcus Bointon <marcus@synchromedia.co.uk>
Date: Mon, 24 Nov 2025 18:17:31 +0100
Subject: [PATCH 7/7] Fix syntax

---
 examples/gmail.phps | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/examples/gmail.phps b/examples/gmail.phps
index 25e18a48..35e49966 100644
--- a/examples/gmail.phps
+++ b/examples/gmail.phps
@@ -83,15 +83,14 @@ if (!$mail->send()) {
     echo 'Message sent!';
     //Section 2: IMAP
     //Uncomment these to save your message in the 'Sent Mail' folder.
-    #if (save_mail($mail->getSentMIMEMessage())) {
-    #    echo "Message saved!";
-    #}
+    #save_mail($mail->getSentMIMEMessage());
 }
 
 //Section 2: IMAP
 //This example uses the directorytree/imapengine IMAP library: https://imapengine.com
 //Earlier versions of this code used the deprecated PHP imap_* functions.
-function save_mail($message) {
+function save_mail($message)
+{
     $mailbox = new \DirectoryTree\ImapEngine\Mailbox([
         'host' => 'imap.gmail.com',
         'port' => 993,
@@ -104,5 +103,4 @@ function save_mail($message) {
     $folder = $mailbox->folders()->find('Sent Mail');
 
     $folder->messages()->append($message);
-    return true;
 }