itinerisltd/wp-phpmailer

WP PHPMailer provides a clean and simple way to configure WordPress-bundled PHPMailer library, allowing you to quickly get started sending mail through a local or cloud based service of your choice.

0.3.0 2022-05-02 17:16 UTC

Requires

• php: ^7.2|^8.0

Requires (Dev)

• 10up/wp_mock: ^0.4.2
• codeception/base: ^3.1
• itinerisltd/itineris-wp-coding-standards: ^0.4.0
• mockery/mockery: ^1.3
• phpstan/phpstan: ^0.12.3
• phpstan/phpstan-strict-rules: ^0.12.0
• roave/security-advisories: dev-master
• roots/wordpress: ^5.5

Conflicts

• itinerisltd/phpmailer-mailhog: *
• johnpbloch/wordpress-core: <5.5
• roots/wordpress: <5.5
• wpackagist-plugin/sendgrid-email-delivery-simplified: *

MIT

• Itineris Limited
• Tang Rufus

• email
• wordpress
• smtp
• phpmailer
• wp

README

WP PHPMailer provides a clean and simple way to configure the WordPress-bundled PHPMailer library, allowing you to quickly get started sending mail through a local or cloud based service of your choice.

• Goal
• Usage
  • Mailhog
  • Mailtrap
  • SendGrid
• Custom Driver
  • Step 1. Define Your Driver
  • Step 2. Register Your Driver
  • Step 3. Define Constants
• Filters
  • wp_phpmailer_driver
  • wp_phpmailer_drivers
  • wp_phpmailer_config_mappings
• Minimum Requirements
• Installation
  • Composer (Recommended)
  • wordpress.org (WP CLI)
  • wordpress.org
  • Build from Source (Not Recommended)
• Common Errors
  • NotFoundException - Driver 'xxx' not found, acceptable values are: aaa, bbb, ccc
• FAQ
  • Where is the settings page?
  • Will you add a settings page?
  • What PHPMailer version bundled?
  • Is it a must to use SMTP?
  • Will you add support for older PHP versions?
  • It looks awesome. Where can I find more goodies like this?
  • Where can I give ⭐⭐⭐⭐⭐ reviews?
• Testing
• Feedback
• Security
• Credits
• License

Goal

Although WordPress bundles the PHPMailer library which allow you sending mail through a local or cloud based service of your choice, different cloud based service requires different configuration. Worse still, most services provide multiple ways for setting them up. For instance: which SendGrid SMTP port provides the highest level of security, 25, 587, 2525 or 465?

WP PHPMailer uses the WordPress-bundled PHPMailer library:

• so you offload the responsibility of updating bundled libraries from plugin authors to WordPress core team and contributors
  • at the time of writing, the official SendGrid plugin's vendor folder hasn't been updated in 2.5 years

WP PHPMailer believes in convention over configuration, we pick the best configuration for each service:

• so you don't waste time going through the documents
• so you don't have to figure out which port and protocol to use
• so you don't miss any security configuration, e.g: SMTPAuth, SMTPSecure, etc
  • unlike the official Mailgun plugin, there is no "use secure SMTP" option because nobody should be using insecure options
• so you only have to provide minimum information
  • take SendGrid for example, only SendGrid API key (with "Mail Send" permission only) is required

WP PHPMailer believes a plugin should "do one thing and do it well":

• unlike the official SendGrid plugin, WP PHPMailer doesn't include the subscription widget nor the stats dashboard

Usage

Pick one driver and define its required constants in wp-config.php.

Mailhog

define('WP_PHPMAILER_DRIVER', 'mailhog');

Mailtrap

define('WP_PHPMAILER_DRIVER', 'mailtrap');

define('MAILTRAP_USERNAME', 'your-mailtrap-username');
define('MAILTRAP_PASSWORD', 'your-mailtrap-password');

SendGrid

define('WP_PHPMAILER_DRIVER', 'sendgrid');

define('SENDGRID_API_KEY', 'your-sendgrid-api-key');

// Optional. Useful if you have email authentication configurated.
define('SENDGRID_FROM_ADDRESS', '[e-mail]');
define('SENDGRID_FROM_NAME', 'John Doe');
define('SENDGRID_FROM_AUTO', true);

Custom Driver

Step 1. Define Your Driver

class MyCustomDriver implements DriverInterface
{
    public static function makeConfig(ConstantRepository $constantRepo): ConfigInterface
    {
        $config = new Config();

        $config->set('auth', true);
        $config->set('host', 'smtp.custom.test');
        $config->set('port', 587);
        $config->set('protocol', 'tls');

        $config->set(
            'username',
            $constantRepo->getRequired('MY_CUSTOM_USERNAME')
        );

        $config->set(
            'password',
            $constantRepo->getRequired('MY_CUSTOM_PASSWORD')
        );

        $config->set(
            'fromAddress',
            $constantRepo->get('MY_CUSTOM_FROM_ADDRESS')
        );
        $config->set(
            'fromName',
            $constantRepo->get('MY_CUSTOM_FROM_NAME')
        );
        $config->set(
            'fromAuto',
            $constantRepo->get('MY_CUSTOM_FROM_AUTO')
        );

        return $config;
    }
}

Step 2. Register Your Driver

add_filter('wp_phpmailer_drivers', function (array $drivers): array {
    $drivers['my-custom-driver'] = MyCustomDriver::class;

    return $drivers;
});

Step 3. Define Constants

// wp-config.php

define('WP_PHPMAILER_DRIVER', 'my-custom-driver');

define('MY_CUSTOM_USERNAME', 'xxx');
define('MY_CUSTOM_PASSWORD', 'xxx');

// Optional.
define('MY_CUSTOM_FROM_ADDRESS', 'xxx');
define('MY_CUSTOM_FROM_NAME', 'xxx');
define('MY_CUSTOM_FROM_AUTO', true);

Filters

wp_phpmailer_driver

$driver = (string) apply_filters('wp_phpmailer_driver', string $wpPhpmailerDriver))

Filters the WP_PHPMAILER_DRIVER constant.

Parameters:

• $wpPhpmailerDriver
  • (string) the value of WP_PHPMAILER_DRIVER constant

wp_phpmailer_drivers

$drivers = (array) apply_filters('wp_phpmailer_drivers', array $drivers)

Filters the available drivers array.

Parameters:

• $drivers
  • (array) the available drivers array

Example:

add_filter('wp_phpmailer_drivers', function (array $drivers): array {
   $drivers['my-custom-driver'] = MyCustomDriver::class;

   return $drivers;
});

wp_phpmailer_config_mappings

$mappings = (array) apply_filters('wp_phpmailer_config_mappings', array $mapings)

Filters the whitelisted PHPMailer configuration (property names) array. 'fromAddress', 'fromName', 'fromAuto' are special. Do not add them in mappings!

Parameters:

• $mapings
  • (array) the whitelisted PHPMailer configuration (property names)

Example:

add_filter('wp_phpmailer_config_mappings', function (array $mappings): array {
    $mappings['xxx'] = 'yyy';

    return $mappings;
});

// The above filter results in:
add_action( 'phpmailer_init', function (PHPMailer $phpmailer) {
    // $this->config comes from `DriverInterface::makeConfig`.
    $phpmailer->xxx = $this->config->get('yyy');
});

Minimum Requirements

• PHP v7.2
• WordPress v5.5

Installation

Composer (Recommended)

composer require itinerisltd/wp-phpmailer

wordpress.org (WP CLI)

wp plugin install wp-phpmailer

wordpress.org

Download from https://wordpress.org/plugins/wp-phpmailer Then, install wp-phpmailer.zip as usual.

Build from Source (Not Recommended)

# Make sure you use the same PHP version as remote servers.
# Building inside docker images is recommended.
php -v

# Checkout source code
git clone https://github.com/ItinerisLtd/wp-phpmailer.git
cd wp-phpmailer
git checkout <the-tag-or-the-branch-or-the-commit>

# Build the zip file
composer release:build

Then, install release/wp-phpmailer.zip as usual.

Common Errors

NotFoundException - Driver 'xxx' not found, acceptable values are: aaa, bbb, ccc

Reason: Driver is not found or not defined.

Troubleshooting:

• Ensure PHP constant is WP_PHPMAILER_DRIVER is correct
• Ensure filter wp_phpmailer_driver is functioning correctly

FAQ

Where is the settings page?

There is no settings page.

All configurations are done by PHP constants and WordPress filters.

Will you add a settings page?

No.

We have seen countless vulnerabilities related to user inputs. Mail settings don't change often and should be configured by a developer. Therefore, WP PHPMailer decided to use PHP constants instead of storing options in WordPress database.

However, if you must, you can use filters to override this behavior.

What PHPMailer version bundled?

This plugin reuse the PHPMailer class bundled with WordPress core.

Thus, you have to keep WordPress core up to date to receive security patches.

Is it a must to use SMTP?

No.

While you can make your own non-SMTP drivers, all default drivers are using SMTP. Pull requests are welcomed.

Will you add support for older PHP versions?

Never! This plugin will only work on actively supported PHP versions.

Don't use it on end of life or security fixes only PHP versions.

It looks awesome. Where can I find more goodies like this?

• Articles on Itineris' blog
• More projects on Itineris' GitHub profile
• More plugins on Itineris and TangRufus wp.org profiles
• Follow @itineris_ltd and @TangRufus on Twitter
• Hire Itineris to build your next awesome site

Where can I give ⭐⭐⭐⭐⭐ reviews?

Thanks! Glad you like it. It's important to let my boss knows somebody is using this project. Please consider:

• leave a 5-star review on wordpress.org
• tweet something good with mentioning @itineris_ltd and @TangRufus
• ⭐ star this Github repo
• 👀 watch this Github repo
• write blog posts
• submit pull requests
• hire Itineris

Testing

composer test
composer phpstan:analyse
composer style:check

Pull requests without tests will not be accepted!

Feedback

Please provide feedback! We want to make this library useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

WP PHPMailer is a Itineris Limited project created by Tang Rufus.

Special thanks to Brandon whose WP SMTP inspired this project.

Full list of contributors can be found here.

License

WP PHPMailer is released under the MIT License.