Merge pull request #2524 from pdscopes/feature/oauth-interface

#2523 OAuth Interface

examples/gmail_xoauth.phps

@@ -1,7 +1,10 @@
 <?php
 
 /**
- * This example shows how to send via Google's Gmail servers using XOAUTH2 authentication.
+ * This example shows how to send via Google's Gmail servers using XOAUTH2 authentication
+ * using the league/oauth2-client to provide the OAuth2 token.
+ * To use a different OAuth2 library create a wrapper class that implements OAuthTokenProvider and
+ * pass that wrapper class to PHPMailer::setOAuth().
  */
 
 //Import PHPMailer classes into the global namespace
@@ -50,6 +53,7 @@ $mail->SMTPAuth = true;
 //Set AuthType to use XOAUTH2
 $mail->AuthType = 'XOAUTH2';
 
+//Start Option 1: Use league/oauth2-client as OAuth2 token provider
 //Fill in authentication details here
 //Either the gmail account owner, or the user that gave consent
 $email = 'someone@gmail.com';
@@ -80,6 +84,16 @@ $mail->setOAuth(
         ]
     )
 );
+//End Option 1
+
+//Option 2: Another OAuth library as OAuth2 token provider
+//Set up the other oauth library as per its documentation
+//Then create the wrapper class that implementations OAuthTokenProvider
+$oauthTokenProvider = new MyOAuthTokenProvider(/* Email, ClientId, ClientSecret, etc. */);
+
+//Pass the implementation of OAuthTokenProvider to PHPMailer
+$mail->setOAuth($oauthTokenProvider);
+//End Option 2
 
 //Set who the message is to be sent from
 //For gmail, this generally needs to be the same as the user you logged in as

src/OAuth.php

@@ -33,7 +33,7 @@ use League\OAuth2\Client\Token\AccessToken;
  *
  * @author  Marcus Bointon (Synchro/coolbru) <phpmailer@synchromedia.co.uk>
  */
-class OAuth
+class OAuth implements OAuthTokenProvider
 {
     /**
      * An instance of the League OAuth Client Provider.

src/OAuthTokenProvider.php

@@ -0,0 +1,44 @@
+<?php
+
+/**
+ * PHPMailer - PHP email creation and transport class.
+ * PHP Version 5.5.
+ *
+ * @see https://github.com/PHPMailer/PHPMailer/ The PHPMailer GitHub project
+ *
+ * @author    Marcus Bointon (Synchro/coolbru) <phpmailer@synchromedia.co.uk>
+ * @author    Jim Jagielski (jimjag) <jimjag@gmail.com>
+ * @author    Andy Prevost (codeworxtech) <codeworxtech@users.sourceforge.net>
+ * @author    Brent R. Matzelle (original founder)
+ * @copyright 2012 - 2020 Marcus Bointon
+ * @copyright 2010 - 2012 Jim Jagielski
+ * @copyright 2004 - 2009 Andy Prevost
+ * @license   http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
+ * @note      This program is distributed in the hope that it will be useful - WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.
+ */
+
+namespace PHPMailer\PHPMailer;
+
+/**
+ * OAuthTokenProvider - OAuth2 token provider interface.
+ * Provides base64 encoded OAuth2 auth strings for SMTP authentication.
+ *
+ * @see     OAuth
+ * @see     SMTP::authenticate()
+ *
+ * @author  Peter Scopes (pdscopes)
+ * @author  Marcus Bointon (Synchro/coolbru) <phpmailer@synchromedia.co.uk>
+ */
+interface OAuthTokenProvider
+{
+    /**
+     * Generate a base64-encoded OAuth token ensuring that the access token has not expired.
+     * The string to be base 64 encoded should be in the form:
+     * "user=<user_email_address>\001auth=Bearer <access_token>\001\001"
+     *
+     * @return string
+     */
+    public function getOauth64();
+}

src/PHPMailer.php

@@ -358,9 +358,9 @@ class PHPMailer
     public $AuthType = '';
 
     /**
-     * An instance of the PHPMailer OAuth class.
+     * An implementation of the PHPMailer OAuthTokenProvider interface.
      *
-     * @var OAuth
+     * @var OAuthTokenProvider
      */
     protected $oauth;
 
@@ -5027,9 +5027,9 @@ class PHPMailer
     }
 
     /**
-     * Get the OAuth instance.
+     * Get the OAuthTokenProvider instance.
      *
-     * @return OAuth
+     * @return OAuthTokenProvider
      */
     public function getOAuth()
     {
@@ -5037,9 +5037,9 @@ class PHPMailer
     }
 
     /**
-     * Set an OAuth instance.
+     * Set an OAuthTokenProvider instance.
      */
-    public function setOAuth(OAuth $oauth)
+    public function setOAuth(OAuthTokenProvider $oauth)
     {
         $this->oauth = $oauth;
     }

src/SMTP.php

@@ -483,7 +483,7 @@ class SMTP
      * @param string $username The user name
      * @param string $password The password
      * @param string $authtype The auth type (CRAM-MD5, PLAIN, LOGIN, XOAUTH2)
-     * @param OAuth  $OAuth    An optional OAuth instance for XOAUTH2 authentication
+     * @param OAuthTokenProvider $OAuth An optional OAuthTokenProvider instance for XOAUTH2 authentication
      *
      * @return bool True if successfully authenticated
      */