Mailer: allow disabling SMTPAutoTLS via config (#9026)

PHPMailer enables SMTPAutoTLS by default, meaning it opportunistically
upgrades a plain SMTP connection to STARTTLS whenever the server
advertises support for it, regardless of the 'secure' => '' setting
documented in config.default.php. Minz_Mailer never read or set
$mail->SMTPAutoTLS, so this behaviour could not be turned off, making
it impossible to talk to SMTP servers with a self-signed or otherwise
untrusted certificate (e.g. a mail server on an internal Docker
network) without importing a custom CA.

Add a new 'auto_tls' key to the 'smtp' config array, defaulting to
true to preserve current behaviour, and wire it through to
$mail->SMTPAutoTLS in Minz_Mailer. Document the new option.

Fixes #2997

Co-authored-by: Gerard Alvear <gerard.alvear@logiqd.me>

config.default.php

@@ -211,6 +211,7 @@ return [
 		'username' => '',
 		'password' => '',
 		'secure' => '', // '', 'ssl' or 'tls'
+		'auto_tls' => true, // maps to PHPMailer’s `SMTPAutoTLS`; set to false to disable opportunistic STARTTLS, e.g. when using a self-signed certificate
 		'from' => 'root@localhost',
 	],
 

docs/en/admins/05_Configuring_email_validation.md

@@ -45,6 +45,7 @@ PHPMailer documentation](https://phpmailer.github.io/PHPMailer/classes/PHPMailer
 		'username' => 'alice', // or maybe alice@example.net
 		'password' => 'yoursecretpassword',
 		'secure' => 'ssl', // '', 'ssl' or 'tls'
+		'auto_tls' => true, // set to false to disable opportunistic STARTTLS, e.g. when using a self-signed certificate
 		'from' => 'alice@example.net',
 	],
 ```

lib/Minz/Configuration.php

@@ -10,7 +10,8 @@ declare(strict_types=1);
  * @property string $environment
  * @property array<string,bool> $extensions_enabled
  * @property-read string $mailer
- * @property-read array{'hostname':string,'host':string,'auth':bool,'username':string,'password':string,'secure':string,'port':int,'from':string} $smtp
+ * @property-read array{'hostname':string,'host':string,'auth':bool,'username':string,'password':string,
+ *  'secure':string,'auto_tls':bool,'port':int,'from':string} $smtp
  * @property string $title
  */
 class Minz_Configuration {

lib/Minz/Mailer.php

@@ -30,7 +30,7 @@ class Minz_Mailer {
 	protected $view;
 
 	private string $mailer;
-	/** @var array{'hostname':string,'host':string,'auth':bool,'username':string,'password':string,'secure':string,'port':int,'from':string} */
+	/** @var array{'hostname':string,'host':string,'auth':bool,'username':string,'password':string,'secure':string,'auto_tls':bool,'port':int,'from':string} */
 	private array $smtp_config;
 	private int $debug_level;
 
@@ -94,6 +94,7 @@ class Minz_Mailer {
 				$mail->Username = $this->smtp_config['username'];
 				$mail->Password = $this->smtp_config['password'];
 				$mail->SMTPSecure = $this->smtp_config['secure'];
+				$mail->SMTPAutoTLS = $this->smtp_config['auto_tls'];
 				$mail->Port = $this->smtp_config['port'];
 			} else {
 				$mail->isMail();