Introduction
This guide builds on the basics outlined in a previously written guide:
Using the PHPMailer library to send messages via SMTP
In an effort to provide a simple and concise guide here, we've left out all of the basics of using PHPMailer. Please review the guide above if you are not already familiar with the basics of using PHPMailer.
Procedure
This guide assumes that you have downloaded the PHPMailer library to the following directory. Please take note that CPANELUSERNAMEHERE represents the cPanel username of your own cPanel user and should not be used literally on your own server.
/home/CPANELUSERNAMEHERE/PHPMailerTest
This guide also assumes that you are logged in as the cPanel user via the Terminal icon in cPanel or via SSH. Please do not ever execute PHP scripts that are intended to be used in a cPanel account as the root user as this is a major security risk for the entire server.
With the PHPMailer library in the above mentioned location you would copy the example form into the document root of your domain. In this example we will assume that we are using the Primary Domain of the cPanel account so the document root is the public_html directory.
cp -v ~/PHPMailerTest/examples/contactform.phps ~/public_html/testForm.php
Next open the testForm.php script with the text editor of your choice and find the require statement which looks like this:
require '../vendor/autoload.php';
Remove the existing require statement from inside of the file and replace it with the following require statements. Be sure to use the full path to the files to avoid problems.
require '/home/CPANELUSERNAMEHERE/PHPMailerTest/src/Exception.php';
require '/home/CPANELUSERNAMEHERE/PHPMailerTest/src/PHPMailer.php';
require '/home/CPANELUSERNAMEHERE/PHPMailerTest/src/SMTP.php';
It's always a good idea to double check the location of the files to make sure that you are using the correct path with the following command:
find ~/ -name PHPMailer.php -or -name Exception.php -or -name SMTP.php
Once you have fixed the require statements, you should update the Email addresses used within the example contact form to the appropriate ones. To keep this guide concise, we're going to keep all of the example email addresses the same because that is all that is required for functionality. It is recommended that while you're learning and testing this out that you only use one email address as well for simplicity, and that the email address that you use is one that is hosted on the same cPanel account that you are testing with. You should also have the password for that email address ready to add to the script. You can use a different email address, but you may run into additional complexities not covered in this guide so a lot of time can be saved by keeping it simple to start.
The following command will replace all of the required email addresses with whatever Email address you use for MYEMAILADDRESS@MYDOMAIN.TLD below. This will also create a backup of the testForm.php file at ~/public_html/testForm.php.bak so that you can revert the change if it doesn't do what you want, or what you were expecting.
sed -i.bak 's/[a-z]\+@example.com/MYEMAILADDRESS@MYDOMAIN.TLD/g' ~/public_html/testForm.php
Next you'll need to determine the domain to use for the SMTP host. Since this guide is assuming that you are using an email account that is hosted on the same cPanel account that the script is installed to, we're going to make use of the server's hostname because this is the most reliable option in most cases. There are many other variations that could be used if you have a preference or knowledge to do otherwise. To find the server's hostname use the following command and then note down the domain that it returns.
hostname
Next you'll need to locate the following lines within the testForm.php script:
$mail->isSMTP();
$mail->Host = 'localhost';
$mail->Port = 25;
Replace those lines with the following:
$mail->SMTPDebug = 2; // Enable verbose debug output
$mail->isSMTP(); // Set mailer to use SMTP
$mail->Host = 'HOSTNAME.GOES.HERE'; // Specify main and backup SMTP servers
$mail->SMTPAuth = true; // Enable SMTP authentication
$mail->Username = 'MYEMAILADDRESS@MYDOMAIN.TLD'; // SMTP username
$mail->Password = 'EMAIL-ACCOUNT-PASSWORD-GOES-HERE'; // SMTP password
$mail->SMTPSecure = 'tls'; // Enable TLS encryption, ssl also accepted
$mail->Port = 587; // TCP port to connect to
NOTE: Be sure to replace the Email address and hostname with your own. Also be sure to disable the SMTPDebug option before using the form in production. Leaving the debug option on in production is a security hazard.
At this point you are ready to test the script. The place in which any PHP errors will be logged depends on the kind of PHP that your server is using. The following command tails both the main Apache error log, and the location where a local error log may be depending on your type of PHP in use. This command will produce an error if the local error log doesn't exist, but you can ignore that.
tail -fn0 /etc/apache2/logs/error_log ~/public_html/error_log
In addition to the locations in the command above you may also want to check ~/logs directory if the above command doesn't show you any error logs and the script is producing a 500 error when you test it. The ~/logs directory is used when your server is making use of PHP-FPM, and the specific log name includes your domain which is why it was not added to the command above.
Now you're ready to test the script by visiting it directly in your browser. If you've setup the script in the public_html directory as outlined in this guide you'd use your primary domain like this:
https://myprimarydomain.tld/testForm.php
Fill out the form and then submit it. You'll find at the top of the resulting page a large amount of debug output that may help you to determine if there is a problem with the SMTP transaction, and then a message with the following if the test was successful:
Message sent! Thanks for contacting us.