Add PSR-3 compatible debug logging

UPGRADING.md

@@ -1,6 +1,6 @@
 # Upgrading from PHPMailer 5.2 to 6.0
 
-PHPMailer 6.0 is a major update containing some backward-compatibility breaks.
+PHPMailer 6.0 is a major update, breaking backward compatibility.
 
 If you're in doubt about how you should be using PHPMailer 6, take a look at the examples as they have all been updated to work in a PHPMailer 6.0 style.
 
@@ -10,17 +10,17 @@ PHPMailer 6.0 requires PHP 5.5 or later, and is fully compatible with PHP 7.0. P
 
 ## Loading PHPMailer
  
-The single biggest change will be in the way that you load PHPMailer. In earlier versions you'll have done this:
+The single biggest change will be in the way that you load PHPMailer. In earlier versions you may have done this:
 
 ```php
-require 'class.phpmailer.php';
-require 'class.smtp.php';
+require 'PHPMailerAutoload.php';
 ```
 
 or
 
 ```php
-require 'PHPMailerAutoload.php';
+require 'class.phpmailer.php';
+require 'class.smtp.php';
 ```
 
 We recommend that you load PHPMailer via composer, using its standard autoloader, which you probably won't need to load if you're using it already, but in case you're not, you will need to do this instead:
@@ -60,6 +60,7 @@ The OAuth2 implementation has been completely redesigned using the [OAuth2 packa
 * Additional classes previously bundled in the `Extras` folder (such as htmlfilter and EasyPeasyICS) have been removed - use equivalent packages from [packagist.org](https://packagist.org) instead.
 
 ##Other upgrade changes
+See the changelog for full details.
 * File structure simplified, classes live in the `src/` folder
 * Most statically called functions now use the `static` keyword instead of `self`, so it's possible to override static internal functions in subclasses, for example `validateAddress()`
 * Complete RFC standardisation on CRLF (`\r\n`) line breaks by default:

changelog.md

@@ -5,8 +5,8 @@ This is a major update that breaks backwards compatibility.
 
 * **Requires PHP 5.5 or later**
 * Uses the `PHPMailer\PHPMailer` namespace
-* File structure simplified, classes live in the `src/` folder
-* The custom autoloader has been removed, now PSR-4 compatible: [**use composer**](https://getcomposer.org)!
+* File structure simplified and PSR-4 compatible, classes live in the `src/` folder
+* The custom autoloader has been removed: [**use composer**](https://getcomposer.org)!
 * Classes & Exceptions renamed to make use of the namespace
 * Most statically called functions now use the `static` keyword instead of `self`, so it's possible to override static internal functions in subclasses, for example `validateAddress()`
 * Complete RFC standardisation on CRLF (`\r\n`) line breaks by default:
@@ -36,8 +36,10 @@ This is a major update that breaks backwards compatibility.
 * `PHPMailer->SingleToArray` is now protected
 * Don't try to use an auth mechanism if it's not supported by the server
 * Reorder automatic AUTH mechanism selector to try most secure method first
-* `Extras` classes have been removed - use packages from [packagist.org](https://packagist.org) instead
+* `Extras` classes have been removed - use alternative packages from [packagist.org](https://packagist.org) instead
 * Better handling of automatic transfer encoding switch in the presence of long lines
+* Simplification of address validation - now uses PHP's filter_var by default, retains advanced options
+* `Debugoutput` now accepts a PSR-3 logger instance
 
 ## Version 5.2.16 (June 6th 2016)
 * Added DKIM example

composer.json

@@ -27,6 +27,7 @@
         "phpunit/phpunit": "4.*"
     },
     "suggest": {
+        "psr/log": "For optional PSR-3 debug logging",
         "league/oauth2-google": "Needed for Google XOAUTH2 authentication",
         "hayageek/oauth2-yahoo": "Needed for Yahoo XOAUTH2 authentication",
         "stevenmaguire/oauth2-microsoft": "Needed for Microsoft XOAUTH2 authentication"

src/PHPMailer.php

@@ -342,8 +342,12 @@ class PHPMailer
      * <code>
      * $mail->Debugoutput = function($str, $level) {echo "debug level $level; message: $str";};
      * </code>
-     *
-     * @var string|callable
+     * Alternatively, you can pass in an instance of a PSR-3 compatible logger, though only `debug`
+     * level output is used:
+     * <code>
+     * $mail->Debugoutput = new myPsr3Logger;
+     * </code>
+     * @var string|callable|Psr\Log\LoggerInterface
      * @see SMTP::$Debugoutput
      */
     public $Debugoutput = 'echo';
@@ -743,6 +747,11 @@ class PHPMailer
         if ($this->SMTPDebug <= 0) {
             return;
         }
+        //Is this a PSR-3 logger?
+        if (is_a($this->Debugoutput, 'Psr\Log\LoggerInterface')) {
+            $this->Debugoutput->debug($str);
+            return;
+        }
         //Avoid clash with built-in function names
         if (!in_array($this->Debugoutput, ['error_log', 'html', 'echo']) and is_callable($this->Debugoutput)) {
             call_user_func($this->Debugoutput, $str, $this->SMTPDebug);

src/SMTP.php

@@ -102,13 +102,17 @@ class SMTP
      * * `echo` Output plain-text as-is, appropriate for CLI
      * * `html` Output escaped, line breaks converted to `<br>`, appropriate for browser output
      * * `error_log` Output to error log as configured in php.ini
-     *
      * Alternatively, you can provide a callable expecting two params: a message string and the debug level:
      * <code>
      * $smtp->Debugoutput = function($str, $level) {echo "debug level $level; message: $str";};
      * </code>
+     * Alternatively, you can pass in an instance of a PSR-3 compatible logger, though only `debug`
+     * level output is used:
+     * <code>
+     * $mail->Debugoutput = new myPsr3Logger;
+     * </code>
      *
-     * @var string|callable
+     * @var string|callable|Psr\Log\LoggerInterface
      */
     public $Debugoutput = 'echo';
 
@@ -199,6 +203,11 @@ class SMTP
         if ($level > $this->do_debug) {
             return;
         }
+        //Is this a PSR-3 logger?
+        if (is_a($this->Debugoutput, 'Psr\Log\LoggerInterface')) {
+            $this->Debugoutput->debug($str);
+            return;
+        }
         //Avoid clash with built-in function names
         if (!in_array($this->Debugoutput, ['error_log', 'html', 'echo']) and is_callable($this->Debugoutput)) {
             call_user_func($this->Debugoutput, $str, $this->do_debug);