Merge pull request #3041

Cleaned up OAuth example

examples/sendoauth2.phps

@@ -1,83 +1,94 @@
 <?php
 
 /**
- * This example uses the SendOauth2 wrapper to support OAuth2 (and Basic) authentication for both Microsoft
- * 365 Exchange email and Google Gmail.
- * Client secrets and X.509 certificates are supported for Exchange. Client secrets are supported for Gmail.
- * Authorization_code grant flow and client_credentials (i.e. application) grant flow for SMTP are supported for
- * Exchange. Authorization_code grant flow is supported for Gmail.
+ * The SendOauth2 wrapper supports OAuth2 and Basic authorization/authentication for
+ * Microsoft 365 Exchange email and Google Gmail. Both TheLeague's Google provider + client
+ * and Google's 'official' GoogleAPI client are supported. The wrapper supports any authentication
+ * mechanism provided by these systems: authorization_code grant and client_credentials grant
+ * (aka Google 'service accounts'), client secrets and X.509 certificates, $_SESSION 'state'
+ * and PKCE code exchanges, and creation on the fly of GoogleAPI's .json credentials files.
  * Appropriate scopes (client permissions) and 'provider' overrides are added automatically.
  *
- * Install with Composer from the decomplexity/SendOauth2 repo.
+ * The wrapper is installed with Composer from the decomplexity/SendOauth2 repo; see its README.
  *
- * SendOauth2 can be also be invoked using less (or even no) arguments - see the repo for details.
- *
- * Needs PHPMailer >=6.6.0 that added support for oauthTokenProvider
- *
- * (The next release [V4] of the wrapper will replace TheLeague's Google provider by Google's own GoogleOauthClient;
- * this will provide support for Google's version of client credentials (Service Accounts) and client certificates)
+ * The wrapper can also be invoked using fewer (or even no) arguments; this is for those websites
+ * that use PHPMailer in several places. See the repo for details.
  */
 
-//Import SendOauth2B class into the global namespace
-use decomplexity\SendOauth2\SendOauth2B;
-//Import PHPMailer classes into the global namespace
-//These must be at the top of your script, not inside a function
+// Import PHPMailer classes
 use PHPMailer\PHPMailer\PHPMailer;
 use PHPMailer\PHPMailer\SMTP;
 use PHPMailer\PHPMailer\Exception;
+// Import SendOauth2B class
+use decomplexity\SendOauth2\SendOauth2B;
 
-//Load Composer's autoloader
+// Uncomment the next two lines to display PHP errors
+// error_reporting(E_ALL);
+// ini_set("display_errors", 1);
+
+// Load Composer's autoloader
 require 'vendor/autoload.php';
 
-//Create an instance; passing `true` enables exceptions
+// Set timezone for SMTP
+date_default_timezone_set('Etc/UTC');
+
+// Create an instance; passing `true` enables exceptions
 $mail = new PHPMailer(true);
 
 try {
- //Server settings
- $mail->SMTPDebug = SMTP::DEBUG_SERVER; //Enable verbose debug output
- $mail->isSMTP(); //Send using SMTP
- $mail->Host = 'smtp.office365.com'; //Set the SMTP server (smtp.gmail.com for Gmail)
- $mail->SMTPAuth = true; //Enable SMTP authentication
- $mail->Username = '[email protected]'; //SMTP username
- $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS; //Enable implicit TLS encryption
- $mail->Port = 465; //TCP port to connect to
- $mail->AuthType = 'XOAUTH2'; // Set AuthType to use XOAUTH2
-
- //Sender and recipients
+ // Server settings
+ $mail->isSMTP(); // Use SMTP
+ $mail->SMTPDebug = SMTP::DEBUG_OFF; // Set DEBUG_LOWLEVEL for SMTP diagnostics
+ $mail->SMTPAuth = true; // Enable SMTP authentication
+ $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS; // Enable implicit TLS encryption
+ $mail->Port = 587; // TCP port; MSFT doesn't like 465
+ $mail->AuthType = 'XOAUTH2'; // Set AuthType to use XOAUTH2 ('LOGIN' for Basic auth)
+
+ // Sender and recipients
  $mail->setFrom('[email protected]', 'Mailer'); // 'Header' From address with optional sender name
- $mail->addAddress('[email protected]', 'Joe User'); //Add a recipient
+ $mail->addAddress('[email protected]', 'Joe User'); // Add a To: recipient
+
+ /**
+ * Authenticate
+ * Note that any ClientCertificatePrivateKey should include the -----BEGIN PRIVATE KEY----- and
+ * -----END PRIVATE KEY-----
+ */
 
- //Authentication
  $oauthTokenProvider = new SendOauth2B(
- ['mail' => $mail, // PHPMailer instance
- 'tenant' => 'long string', // tenant GUID or domain name. Null for Gmail
- 'clientId' => 'long string',
- 'clientSecret' => 'long string', // or null if using a certificate
- 'clientCertificatePrivateKey' => 'extremely long string', // or null if using a clientSecret
- 'clientCertificateThumbprint' => 'long string', // or null if using a clientSecret
- 'serviceProvider' => 'Microsoft', // or Google
- 'authTypeSetting' => $mail->AuthType, // is set above - or insert here as 'XOAUTH2'
- 'mailSMTPAddress' => '[email protected]', // Envelope/mailFrom/reverse-path From address
- 'hostedDomain' => 'mydomain.com', // Google only (and optional)
- 'refreshToken' => 'very long string',
- 'grantTypeValue' => 'authorization_code', // or 'client_credentials' (Microsoft only)
- ]
+ [
+ 'mail' => $mail, // PHPMailer instance
+ 'clientId' => 'long string', // for Google service account, Unique ID
+ 'clientSecret' => 'long string', // or null if using a certificate
+ 'clientCertificatePrivateKey' => 'ultra long string', // or null if using a clientSecret
+ 'clientCertificateThumbprint' => 'long string', // or null if using a clientSecret
+ 'serviceProvider' => 'Microsoft', // literal: also 'Google' or 'GoogleAPI'
+ 'authTypeSetting' => $mail->AuthType, // is set above - or insert here as 'XOAUTH2'
+ 'mailSMTPAddress' => '[email protected]', // Envelope/mailFrom/reverse-path From address
+ 'refreshToken' => 'very long string', // null if grantType is 'client_credentials'
+ 'grantType' => 'authorization_code', // or 'client_credentials'
+
+ 'tenant' => 'long string', // MSFT tenant GUID. Null for Gmail
+
+ 'hostedDomain' => 'mydomain.com', // Any Google (and optional). Null for MSFT
+ 'projectID' => 'string', // GoogleAPI only. Else null
+ 'serviceAccountName' => 'string', // GoogleAPI service account only. Else null
+ 'impersonate' => '[email protected]', // Google API service account only. Else null
+ // (Google Wspace email adddress, not @gmail)
+ ]
  );
- /**
- * If an argument (above) has a null value, the argument can be omitted altogether.
- * ClientCertificatePrivateKey should include the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----
- */
 
- $mail->setOAuth($oauthTokenProvider); //Pass OAuthTokenProvider to PHPMailer
 
- //Content
- $mail->isHTML(true); //Set email format to HTML
+ $mail->setOAuth($oauthTokenProvider); // Pass OAuthTokenProvider to PHPMailer
+ $mail->Host = 'smtp.office365.com'; // Set SMTP server (smtp.gmail.com for Gmail)
+
+ // Content
+ $mail->isHTML(true); // Set email format to HTML
  $mail->Subject = 'Here is the subject';
  $mail->Body = 'This is the HTML message body <b>in bold!</b>';
  $mail->AltBody = 'This is the body in plain text for non-HTML mail clients';
 
  $mail->send();
  echo 'Message has been sent';
 } catch (Exception $e) {
- echo "Message could not be sent. Mailer Error: {$mail->ErrorInfo}";
+ echo 'Message could not be sent. Mailer Error: ' . htmlspecialchars($mail->ErrorInfo, ENT_QUOTES);
 }