jinexus/zend-notification

JiNexus/Zend-Notification provides a simple, chainable wrapper for creating and sending responsive email templates using some zend components (such as zend-mail and zend-view).

1.0.1 2017-05-01 11:16 UTC

Requires

• php: ^5.6 || ^7.0
• zendframework/zend-config: ^3.1.0
• zendframework/zend-filter: ^2.7.1
• zendframework/zend-mail: ^2.7.3
• zendframework/zend-servicemanager: ^3.3.0
• zendframework/zend-view: ^2.9.0

Requires (Dev)

• phpunit/phpunit: ^5.7.19

BSD-3-Clause

• Jimvirle Calago

• mail
• zf2
• notification
• zf3

README

JiNexus/Zend-Notification is a component that extends and utilized the components of Zend-Mail, Zend-View, Zend-Config, Zend-Servicemanager and Zend-Filter to generate and send a well layout emails. This component also uses Cerberus-Responsive as a sample base email template.

• File issues at https://github.com/JiNexus/zend-notification/issues
• Documentation is at https://github.com/JiNexus/zend-notification

Installation

It's recommended that you use Composer to install JiNexus/Zend-Notification.

$ composer require jinexus/zend-notification

This will install JiNexus/Zend-Notification and all required dependencies. JiNexus/Zend-Notification requires PHP 5.6 or latest.

Basic Usage

A basic usage consists of one or more recipients, a subject, a body/content and a sender. To send such a mail using JiNexus/Zend-Notification, do the following:

<?php 
use JiNexus\Zend\Notification\Notification;

$notification = new Notification();
$notification->setFrom('[e-mail]', 'Sender Name')
    ->setTo('[e-mail]', 'Recipient Name')
    ->setSubject('Sample Subject')
    ->setContent(
        'This is the body/content of the email, you can write here your thoughts.' .
        'I\'ve got everything yet nothing to write, for my thoughts are in a constant fight.'
    )
    ->send();

By default JiNexus/Zend-Notification is using Zend\Mail\Transport\Sendmail to send an email.

Adding Multiple Recipients

Method 1: Method chaining the addTo() method

<?php 
use JiNexus\Zend\Notification\Notification;

$notification = new Notification();
$notification->setFrom('[e-mail]', 'Sender Name')
    ->setTo('[e-mail]', 'Recipient One')
    ->addTo('[e-mail]', 'Recipient Two')
    ->addTo('[e-mail]', 'Recipient Three')
    ->setSubject('Your character defines you')
    ->setContent(
        'There are two things that defines you. Your patience to learn when you don\'t know anything, 
        and your attitude to share when you know everything.'
    )
    ->send();

Method 2: Passing array to setTo() method

<?php 
use JiNexus\Zend\Notification\Notification;

$notification = new Notification();
$notification->setFrom('[e-mail]', 'Sender Name')
    ->setTo(['[e-mail]', '[e-mail]'], 'Common Name')
    ->setSubject('What makes me superior?')
    ->setContent(
        'The fact that I don\'t believe that I\'m better than anyone else 
        gives me an inevitable sense of superiority.'
    )
    ->send();

Method 3: Passing array to addTo() method

<?php 
use JiNexus\Zend\Notification\Notification;

$notification = new Notification();
$notification->setFrom('[e-mail]', 'Sender Name')
    ->addTo(['[e-mail]', '[e-mail]'], 'Common Name')
    ->setSubject('I\'m from 90\'s')
    ->setContent(
        'Let me tell you about a magical time. The rock stars were suicidal, 
        the rappers were criminals, and wrestling was real. It was the 90\'s'
    )
    ->send();

Note: The difference between setTo() and addTo() method is that setTo() overwrites the existing data while addTo() appends to the existing data. In short all methods that are prefix with set's and add's behave in the same manner.

You can also add recipients to carbon-copy ("Cc:") or blind carbon-copy ("Bcc:").

<?php 

$notification->setCc('[e-mail]', 'Recipient Cc');
$notification->setBcc('[e-mail]', 'Recipient Bcc');

Or

<?php 
$notification->addCc('[e-mail]', 'Recipient Cc');
$notification->addBcc('[e-mail]', 'Recipient Bcc');

Note: setCc(), setBcc, addCc() and addBcc methods also accepts array of recipients and can also be use in method chaining.

If you want to specify an alternate address to which replies may be sent, that can be done, too.

<?php 
$notification->setReplyTo('[e-mail]', 'Jimvirle');

Or

<?php 
$notification->addReplyTo('[e-mail]', 'Jimvirle');

Interestingly, RFC-822 allows for multiple "From:" addresses. When you do this, the first one will be used as the sender, unless you specify a "Sender:" header. The Notification class allows for this by utilizing the Zend-Mail.

<?php
/*
 * Mail headers created:
 * From: Kheven Bitoon <[e-mail]>, Rogelio Carrillo <[e-mail]>
 * Sender: Jimvirle Calago <[e-mail]>
 */
$notification->addFrom('[e-mail]', 'Kheven Bitoon');
$notification->addFrom('[e-mail]', 'Rogelio Carrillo');
$notification->setSender('[e-mail]', 'Jimvirle Calago');

By default JiNexus/Zend-Notification provides an HTML content upon sending the email. And there are instances that you may want to choose a Text content. To do that you have to set the type of your email by:

<?php 
/*
 * This will set your email to a text content.
 */
$notification->setType('text');

Or

<?php 
/*
 * This will set your email to an html content.
 */
$notification->setType('html');

Adding Attachments To Email

JiNexus/Zend-Notification directly provides you the ability to create and use mail attachments.

<?php 
/*
 * You can also set multiple attachments.
 */
$notification->setAttachments([
    'absolute-path-of-the-file.jpg',
    'this-is-a-multiple-attachment.pdf',
]);

Advance Usage

Advance usage allows you to assemble your own layout and set the right template to be your email's content. JiNexus/Zend-Notification uses Cerberus-Responsive as a sample base email template (You can replace it by your own choice, later when we tackle about setConfig() method). Refer to the src/view/layout and src/view/template

To do this all you have is follow the example below:

<?php 
use JiNexus\Zend\Notification\Notification;

$notification = new Notification();
$notification->setFrom('[e-mail]', 'Sender Name')
    ->setTo('[e-mail]', 'Recipient Name')
    ->setSubject('Sample Subject')
    ->assemble()
    ->send();

By default JiNexus/Zend-Notification will look to the built in configuration under config/notification.global.php to feed the assemble() required configs. To overwrite this default configuration, you have to call the setConfig() method and pass your own array of configs.

To do this all you have is follow the example below:

<?php 
use JiNexus\Zend\Notification\Notification;

$notification = new Notification();
$notification->setFrom('[e-mail]', 'Sender Name')
    ->setTo('[e-mail]', 'Recipient Name')
    ->setSubject('Sample Subject')
    ->setConfig([
            'notification' => [
                'footer' => __DIR__ . '/src/view/layout/footer.phtml',
                'header' => __DIR__ . '/src/view/layout/header.phtml',
                'layout' => __DIR__ . '/src/view/layout/layout.phtml',
                'template' => __DIR__ . '/src/view/template/confirmation-email.phtml',
            ]
        ])
    ->assemble()
    ->send();

Must: Method chaining on the available methods specifically setConfig(), assemble() and send() has their own precedence to follow, they must be called in the right order:

• If you want to call setConfig(), it must be called before assemble() method.
• If you want to call assemble(), it must be called before send() method.
• And lastly, send() method must be called last.

Note: Array keys are strict and must be followed accordingly, you can replace values as long as it exist.

Passing and Parsing a data to the Header - header.phtml

<?php 
$notification->setHeaderData(['greetings' => 'Hello from the other side!']);

Now you can parse the data to your header.phtml, by:

<?php echo $this->greetings; ?>

Passing and Parsing a data to the Footer - footer.phtml

<?php 
$notification->setFooterData([
    'company' => 'JiNexus Inc.',
    'address' => 'Cebu City, Cebu, 6000, PH',
]);

Now you can parse the data to your footer.phtml, by:

<?php echo $this->company; ?>
<?php echo $this->address; ?>

Passing and Parsing a data to the Template - any-email-template.phtml

<?php 
$notification->setTemplateData([
    'fullName' => 'Jimvirle Calago',
    'message' => 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
    'token' => '$2y$10$2pebvLw6RhmqiybYg6qNr.F.lCIEYf0HzPrKAxNTsrRZLRI5uhh1m'
]);

Now you can parse the data to your any-email-template.phtml, by:

<?php echo $this->fullName; ?>
<?php echo $this->message; ?>
<?php echo $this->token; ?>

Must: setHeaderData(), setFooterData() and setTemplateData() must be called before the assemble() method.

Transports and setting up their own parameters or options.

Transports take care of the actual delivery of mail. Typically, you only need to worry about two possibilities: using PHP's native mail() functionality, which uses system resources to deliver mail, or using the SMTP protocol for delivering mail via a remote server.

You can define your own transport by using setTransport() method.

Available Values:

- sendmail
- smtp
- inMemory

Sendmail

By default if you don't define your transport JiNexus/Zend-Notification will automatically use sendmail. However if by any chance you want to pass a parameter to the sendmail, you can do it by:

<?php 
$notification->setTransport('sendmail');
$notification->setSendmailTransportParameters('[e-mail]');
$notification->send();

Chose your transport wisely

Although the sendmail transport is the transport that requires least configuration, it may not be suitable for your production environment. This is because emails sent using the sendmail transport will be more often delivered to SPAM-boxes. This can partly be remedied by using the SMTP Transport combined with an SMTP server that has an overall good reputation. Additionally, techniques such as SPF and DKIM may be employed to ensure even more email messages are delivered successfully.

SMTP

Below is a sample configuration of SMTP transport:

<?php 
$notification->setTransport('smtp');
$notification->setSmtpTransportOptions([
    'host' => 'smtp.gmail.com',
    'port' => 587,
    'connection_class'  => 'plain',
    'connection_config' => [
        'username' => '[e-mail]',
        'password' => 'my-app-password',
        'ssl' => 'tls',
    ],
]);
$notification->send();

InMemory

The InMemory transport is primarily of interest when in development or when testing.

Below is a sample configuration of InMemory transport:

<?php 
$notification->setTransport('inMemory');
$notification->send();

Snapshots

To Do's

• Create a Unit Test
• Add Get and Set Encoding extensions
• Add Get and Set Headers extensions
• Add support for File transport
• Add getLastMessage() for InMemory transport
• Improve Documentation (Here's comes the most boring part~) #grumble

Contributing

Before contributing please read the Contributing File for details.

Security

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

Credits

• Jimvirle Calago
• All Contributors

Dependency

• Zend-Mail
• Zend-View
• Zend-Config
• Zend-ServiceManager
• Zend-Filter

License

The JiNexus/Zend-Notification is an open source project that is licensed under the BSD 3-Clause License. See License File for more information. JiNexus reserves the right to change the license of future releases.

Change log

For the most recent change log, visit the Releases Page or the Changelog File.

Donations

Donations are greatly appreciated!

A man has to code for food. A man must do what he feels needs to be done, even if it is dangerous or undesirable.