2017 © Pedro Peláez
 

library mailwrapper

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

image

byjg/mailwrapper

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  • Monday, March 12, 2018
  • by byjg
  • Repository
  • 4 Watchers
  • 2 Stars
  • 10,061 Installations
  • PHP
  • 1 Dependents
  • 0 Suggesters
  • 4 Forks
  • 0 Open issues
  • 17 Versions
  • 12 % Grown

The README.md

Mail Wrapper

Build Status Opensource ByJG GitHub source GitHub license GitHub release, (*1)

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The motivation is create a single interface for sending mail doesn't matter the sender. There are three options available:, (*2)

  • SMTP (with SSL/TLS)
  • AWS SES (using API directly)
  • Mailgun (using API directly)

How to use

The MailWrapper has your classes totally decoupled in three parts:, (*3)

  • The Envelope: the mail envelope. Defines the mail sender, recipients, body, subject, etc;
  • The Mailer: the responsible to deal with the process of send the envelope
  • The Register: Will register the available Mailers in the system.

Envelope Class

MailWrapper provides a envelope class with all the basic necessary attributes to create an email. As this Envelope class are totally decoupled from the Mailer engine, you can use it also as DTO. See an example below: (do not forget require "vendor/autoload.php"), (*4)

<?php
// Create the email envelope
$envelope = new ByJG\Mail\Envelope();
$envelope->setFrom('johndoe@example.com', 'John Doe');
$envelope->addTo('jane@example.com');
$envelope->setSubject('Email Subject');
$envelope->setBody('html text body');

Sending the email

Once you have created the envelope you can send the email. Basically you have to register in the fabric all mailer you intend to use and then create the mailer:, (*5)

<?php
// Register the available class
\ByJG\Mail\MailerFactory::registerMailer(\ByJG\Mail\Wrapper\PHPMailerWrapper::class);
\ByJG\Mail\MailerFactory::registerMailer(\ByJG\Mail\Wrapper\MailgunApiWrapper::class);

// Create the proper mailer based on the scheme
// In the example below will find the "mailgun" scheme
$mailer = \ByJG\Mail\MailerFactory::create('mailgun://api:YOUR_API_KEY@YOUR_DOMAIN');

// Send the email:
$mailer->send($envelope);

You can create the mailer directly without the factory:, (*6)

<?php
$mailer = new \ByJG\Mail\Wrapper\MailgunApiWrapper(
    new \ByJG\Util\Uri(
        'mailgun://your_api_key@YOUR_DOMAIN'
    )
);

// Send the email:
$mailer->send($envelope);

Sending attachment

<?php
$envelope = new \ByJG\Mail\Envelope('from@email.com', 'to@email.com', 'Subject', 'Body');
$envelope->addAttachment('name_of_attachement', '/path/to/file', 'mime/type');
$mailer->send($envelope);

Adding attachment as Embed Image

Adding an image as a inline attachment (or Embed) your mail reader will not show as download but you can use it as an local image in your email., (*7)

See the example:, (*8)

<?php
$envelope = new \ByJG\Mail\Envelope('from@email.com', 'to@email.com', 'Subject');
$envelope->addEmbedImage('mycontentname', '/path/to/image', 'mime/type');
$envelope->setBody('<img src="cid:mycontentname" />');
$mailer->send($envelope);

The connection url

To create a new sender you have to define a URL like that:, (*9)

scheme://username:password/smtpserver:port

The options are:, (*10)

Part Description
scheme The email scheme: smtp, ssl, tls, mandrill and ses. Note that mandrill and ses use your own private api
username The username
password The password
smtpserver The SMTP Host
port The SMTP Port

The protocols available are:, (*11)

Scheme Description URI Pattern Mailer Object
smtp SMTP over insecure connection smtp://username:password@host:25 PHPMailerWrapper
tls SMTP over secure TLS connection tls://username:password@host:587 PHPMailerWrapper
ssl SMTP over secure SSL connection ssl://username:password@host:587 PHPMailerWrapper
sendmail Sending Email using PHP mail() sendmail://localhost SendMailWrapper
mailgun Sending Email using Mailgun API mailgun://YOUR_API_KEY@YOUR_DOMAIN MailgunApiWrapper
ses Sending Email using Amazon AWS API ses://ACCESS_KEY_ID:SECRET_KEY@REGION AmazonSesWrapper
fakesender Do nothing fakesender://anything FakeSenderWrapper

Gmail specifics

From December 2014, Google started imposing an authentication mechanism called XOAUTH2 based on OAuth2 for access to their apps, including Gmail. This change can break both SMTP and IMAP access to gmail, and you may receive authentication failures (often "5.7.14 Please log in via your web browser") from many email clients, including PHPMailer, Apple Mail, Outlook, Thunderbird and others. The error output may include a link to https://support.google.com/mail/bin/answer.py?answer=78754, which gives a list of possible remedies., (*12)

There are two main solutions:, (*13)

Sending through SMTP

You have to enable the option "Allow less secure apps". It does not really make your app significantly less secure. Reportedly, changing this setting may take an hour or more to take effect, so don't expect an immediate fix. You can start changing here, (*14)

The connection string for sending emails using SMTP through GMAIL is:, (*15)

tls://YOUREMAIL@gmail.com:YOURPASSWORD@smtp.gmail.com:587

Sending Through XOAuth2

This option is currently unsupported., (*16)

Further information and documentation on how to set up can be found on this wiki page., (*17)

Amazon SES API specifics

The connection url for the AWS SES api is:, (*18)

ses://ACCESS_KEY_ID:SECRET_KEY@REGION

The access_key_id and secret_key are created at AWS Control Panel. The region can be us-east-1, etc., (*19)

Mailgun API specifics

The connection url for the Mailgun api is:, (*20)

mailgun://YOUR_API_KEY@YOUR_DOMAIN

The YOUR_API_KEY and YOUR_DOMAIN are defined at Mailgun Control Panel., (*21)

The Region of the endpoint can be configured by query parameter "region" (example: mailgun://api-key@mg.domain.cz?region=eu), (*22)

Valid values are: us and eu., (*23)

Sendmail Specifics

The connection url for the Sendmail is:, (*24)

sendmail://localhost

You need to setup in the php.ini the email relay., (*25)

Implementing your Own Wrappers

To implement your own wrapper you have to create a class inherited from: ByJG\Mail\Wrapper\BaseWrapper and implement how to send in the method: public function send(Envelope $envelope);, (*26)

class MyWrapper extends \ByJG\Mail\Wrapper\BaseWrapper
{
    public static function schema()
    {
        return ['mywrapper'];
    }

    public function send(Envelope $envelope)
    {
        // Do how to send the email using your library
    }

    // You can create your own validation methods.
    public function validate(Envelope $envelope)
    {
        parent::validate($envelope);
    }
}

Install

composer require "byjg/mailwrapper"

Running Tests

./vendor/bin/phpunit

Dependencies

flowchart TD
    byjg/mailwrapper --> ext-curl
    byjg/mailwrapper --> byjg/convert
    byjg/mailwrapper --> byjg/webrequest
    byjg/mailwrapper --> aws/aws-sdk-php
    byjg/mailwrapper --> phpmailer/phpmailer

Open source ByJG, (*27)

The Versions

12/03 2018

dev-master

9999999-dev

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

The Development Requires

by João Gilberto Magalhães

12/03 2018

2.0.3

2.0.3.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

The Development Requires

by João Gilberto Magalhães

07/03 2018

2.0.2

2.0.2.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

The Development Requires

by João Gilberto Magalhães

29/11 2017

2.0.1

2.0.1.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

29/05 2017

2.0.0

2.0.0.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

03/02 2017

1.1.1

1.1.1.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

07/09 2016

1.1.0

1.1.0.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

28/02 2016

1.0.9

1.0.9.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

19/01 2016

1.0.8

1.0.8.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

13/11 2015

1.0.7

1.0.7.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

12/11 2015

1.0.6

1.0.6.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

10/11 2015

1.0.5

1.0.5.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

12/08 2015

1.0.4

1.0.4.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

10/08 2015

1.0.3

1.0.3.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

10/08 2015

1.0.2

1.0.2.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

07/08 2015

1.0.1

1.0.1.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães

04/08 2015

1.0.0

1.0.0.0

A lightweight wrapper for send mail. The interface is tottaly decoupled from the sender. The sender availables are: PHP Mailer, AWS SES Api, Mandril Api.

  Sources   Download

MIT

The Requires

 

by João Gilberto Magalhães