How should I upgrade from PHPMailer 5.2 to 6.0?

Question

I have a script that currently uses a recent version of PHPMailer 5.2.x. PHPMailer 6.0 has been released, but says it will break backward compatibility – what do I need to do to upgrade?

<?php
require 'PHPMailerAutoload.php';

$mail = new PHPMailer;

//$mail->SMTPDebug = 3;                               // Enable verbose debug output

$mail->isSMTP();                                      // Set mailer to use SMTP
$mail->Host = 'smtp1.example.com;smtp2.example.com';  // Specify main and backup SMTP servers
$mail->SMTPAuth = true;                               // Enable SMTP authentication
$mail->Username = '[email protected]';                 // SMTP username
$mail->Password = 'secret';                           // SMTP password
$mail->SMTPSecure = 'tls';                            // Enable TLS encryption, `ssl` also accepted
$mail->Port = 587;                                    // TCP port to connect to

$mail->setFrom('[email protected]', 'Mailer');
$mail->addAddress('[email protected]', 'Joe User');     // Add a recipient
$mail->addAddress('[email protected]');               // Name is optional
$mail->addReplyTo('[email protected]', 'Information');
$mail->addCC('[email protected]');
$mail->addBCC('[email protected]');

$mail->addAttachment('/var/tmp/file.tar.gz');         // Add attachments
$mail->addAttachment('/tmp/image.jpg', 'new.jpg');    // Optional name
$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';

if(!$mail->send()) {
    echo 'Message could not be sent.';
    echo 'Mailer Error: ' . $mail->ErrorInfo;
} else {
    echo 'Message has been sent';
}

Answer 1

The major things that have changed in PHPMailer 6.0:

• Requires PHP 5.5 or later (up from 5.0)
• Uses a namespace
• Class filenames and locations have changed
• Additional unrelated "extras" classes have been removed

There are many other smaller changes which you can read about in the changelog, and also the official upgrade guide, but these are the ones most likely to affect you.

Upgrading via composer

To upgrade via composer, change the entry in the require section of your composer.json file, and then run composer update phpmailer/phpmailer:

"phpmailer/phpmailer": "~6.0"

This will update only PHPMailer, and will not touch any other dependencies.

PHPMailer uses a semver release numbering policy, and that pattern will match all future releases in the 6.x series. This is a change from the previously recommended ~5.2 pattern.

Loading class files

For the example script given, we mainly need to change how the class is loaded. The autoloader is no longer there, so you either need to be using composer (in which case you won't need to change anything - the standard composer autoloader will do it automatically), or you need to load the classes yourself.

With composer:

require 'vendor/autoload.php';

Without composer:

require 'src/PHPMailer.php';
require 'src/SMTP.php';
require 'src/Exception.php';

Namespacing

The PHPMailer classes are in the PHPMailer\PHPMailer namespace, so you either need to work in that namespace, or import them into your own or the global namespace, for example:

//Import PHPMailer classes into the global namespace
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

Note that these must be placed before the require lines. After that you can use the original class names you're used to:

$mail = new PHPMailer;

Alternatively, you can refer to their fully-qualified names directly, without the use statements, for example:

$mail = new PHPMailer\PHPMailer\PHPMailer;

The reason this class ends up with this "triple name" is because it's the PHPMailer class, in the PHPMailer project, owned by the PHPMailer organisation. This allows it to be differentiated from other forks of PHPMailer, other projects by the PHPMailer organisation, and other classes within the project.

Exceptions

Other than the name change from phpmailerException, exceptions work the same way as in previous versions, but you need to look out for the namespace when catching:

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

$mail = new PHPMailer(true);
try {
    ...
} catch Exception($e) {
    //$e is an instance of PHPMailer\PHPMailer\Exception
} catch \Exception ($e) {
    //$e is an instance of the PHP built-in Exception class
}

Documentation

All documentation and example code has been updated for 6.0 too. The best place to start is the readme file or the project wiki, where you will find links to the ever-popular troubleshooting guide, numerous tutorials, and generated API documentation. If you're just starting out, base your code on the examples provided in the examples folder.

Getting help

If you have a problem using PHPMailer, first of all search on Stack Overflow for your specific error message and under the PHPMailer tag. If you think you have found a bug in PHPMailer, report it on the github project (hint - being unable to connect to mail servers from your GoDaddy server is not a PHPMailer bug!)