2017 © Pedro Peláez
 

library 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).

image

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).

  • Thursday, June 21, 2018
  • by JiNexus
  • Repository
  • 1 Watchers
  • 3 Stars
  • 6 Installations
  • HTML
  • 0 Dependents
  • 0 Suggesters
  • 1 Forks
  • 1 Open issues
  • 5 Versions
  • 0 % Grown

The README.md

JiNexus/Zend-Notification

Build Status Minimum PHP Version Latest Stable Version Total Downloads License Donate, (*1)

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., (*2)

  • 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., (*3)

$ composer require jinexus/zend-notification

This will install JiNexus/Zend-Notification and all required dependencies. JiNexus/Zend-Notification requires PHP 5.6 or latest., (*4)

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:, (*5)

setFrom('sender@example.com', 'Sender Name')
    ->setTo('recipient@example.com', '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](https://docs.zendframework.com/zend-mail/transport/intro/#quick-start) to send an email.

### Adding Multiple Recipients

**Method 1: Method chaining the `addTo()` method**

```php
setFrom('sender@example.com', 'Sender Name')
    ->setTo('recipientOne@example.com', 'Recipient One')
    ->addTo('recipientTwo@example.com', 'Recipient Two')
    ->addTo('recipientThree@example.com', '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
setFrom('sender@example.com', 'Sender Name')
    ->setTo(['recipientOne@example.com', 'recipientTwo@example.com'], '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
setFrom('sender@example.com', 'Sender Name')
    ->addTo(['recipientOne@example.com', 'recipientTwo@example.com'], '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
setCc('recipientCc@example.com', 'Recipient Cc');
$notification->setBcc('recipientBcc@example.com', 'Recipient Bcc');
```
**Or**

```php
addCc('recipientCc@example.com', 'Recipient Cc');
$notification->addBcc('recipientBcc@example.com', '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
setReplyTo('jimvirle@example.com', 'Jimvirle');
```

**Or**

```php
addReplyTo('jimvirle@example.com', 'Jimvirle');
```

##### Interestingly, [RFC-822](https://www.ietf.org/rfc/rfc822.txt) 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
, Rogelio Carrillo 
 * Sender: Jimvirle Calago 
 */
$notification->addFrom('kheven@example.com', 'Kheven Bitoon');
$notification->addFrom('rogelio@example.com', 'Rogelio Carrillo');
$notification->setSender('jimvirle@example.com', '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
setType('text');
```

**Or**

```php
setType('html');
```

### Adding Attachments To Email

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

```php
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
setFrom('sender@example.com', 'Sender Name')
    ->setTo('recipient@example.com', '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
setFrom('sender@example.com', 'Sender Name')
    ->setTo('recipient@example.com', '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
setHeaderData(['greetings' => 'Hello from the other side!']);
```

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

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

Now you can parse the data to your footer.phtml, by:, (*6)

company; ?>
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:, (*7)

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

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

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., (*9)

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

Available Values:, (*11)

- 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:, (*12)

<?php 
$notification->setTransport('sendmail');
$notification->setSendmailTransportParameters('-freturn_to_me@example.com');
$notification->send();

Chose your transport wisely, (*13)

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., (*14)

SMTP

Below is a sample configuration of SMTP transport:, (*15)

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

InMemory

The InMemory transport is primarily of interest when in development or when testing., (*16)

Below is a sample configuration of InMemory transport:, (*17)

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

Snapshots

snapshot-01 snapshot-02, (*18)

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., (*19)

Security

If you discover security related issues, please email jinexus.zend@gmail.com instead of using the issue tracker., (*20)

Credits

Dependency

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., (*21)

Change log

For the most recent change log, visit the Releases Page or the Changelog File., (*22)

Donations

Donations are greatly appreciated!, (*23)

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., (*24)

paypal, (*25)

The Versions

21/06 2018

dev-master

9999999-dev https://github.com/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).

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

by Jimvirle Calago

mail zf2 notification zf3

01/05 2017

1.x-dev

1.9999999.9999999.9999999-dev https://github.com/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).

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

by Jimvirle Calago

mail zf2 notification zf3

01/05 2017

dev-development

dev-development https://github.com/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).

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

by Jimvirle Calago

mail zf2 notification zf3

01/05 2017

1.0.1

1.0.1.0 https://github.com/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).

  Sources   Download

BSD-3-Clause

The Requires

 

The Development Requires

by Jimvirle Calago

mail zf2 notification zf3

29/04 2017

1.0.0

1.0.0.0 https://github.com/JiNexus/zend-notification

JiNexus/Zend-Notification is an extension from selected zend components that helps you quickly send an email with responsive templates or create your own email templates.

  Sources   Download

BSD-3-Clause

The Requires

 

by Jimvirle Calago

mail zf2 notification zf3