aldoanizio/carteiro

Lightweight SMTP Mailer Class for Mako Framework 4.2

Carteiro Mailer

This is a lightweight SMTP mailer package for Mako Framework >=4.2., _(*1)

Install

Use composer to install. Simply add package to your project., _(*2)

composer require aldoanizio/carteiro:*

So now you can update your project with a single command., _(*3)

composer update

Register Service

After installing you'll have to register the package in your app/config/application.php file., _(*4)

    /**
     * ---------------------------------------------------------
     * Packages
     * ---------------------------------------------------------
     *
     * Packages to boot during the application boot sequence.
     * They will be booted in the order that they are defined.
     */

    'packages' =>
    [
        ....
        'aldoanizio\carteiro\CarteiroPackage',
    ],

Configuring

There are two ways to configure your package. The first is editing config file directly in packages folder: app/packages/carteiro/config/config.php and input the necessary information., _(*5)

If you like you can copy the package's config file app/packages/carteiro/config/config.php into app/config/packages/carteiro folder and the application will load that file instead of the one located in the package. This makes it possible to update the package while keeping your custom settings., _(*6)

Basic Usage

To send emails just use the create method parsing some data., _(*7)

$this->carteiro->create('my.email.view', $data, function($mail)
{
    $mail->subject('Hello World');

    $mail->to('foo@bar.com', 'John Doe');
});

The first argument passed to the create method is the name of the view that should be used as the e-mail body. If passed as string will set mail body to use html format., _(*8)

The second is the $data that should be passed to the view., _(*9)

The third is a Closure allowing you to specify various options on the e-mail message. Also using closure you can access other variables., _(*10)

Message format

You can also specify a plain text view to use in addition to an html view. To do this you need to use an array to define wich view to use in each format., _(*11)

$this->carteiro->create(['text' => 'my.text.view', 'html' => 'my.html.view'], $data, function($mail) use ($newUser)
{
    $mail->subject('Welcome New User');

    $mail->to($newUser->email, $newUser->name);
}

Or just use text key to send email as a plain text only., _(*12)

$this->carteiro->create(['text' => 'my.text.view'], $data, function($mail) use ($newUser)
{
    $mail->subject('Welcome New User');

    $mail->to($newUser->email, $newUser->name);
}

Raw content data

Sometimes you need to send emails using a content that do not depends of a view file. For example if you would like to send a custom message to one of your customers stored in database., _(*13)

To do this you can make use of raw key to parse a custom content. Notice in this case you don't need to use a view data so pass an empty array to second parameter., _(*14)

// Your form post data
$postData = $this->request->post();

// ORM
$customer = Custommer::get($postData['customer_id']);

// Send message
$this->carteiro->create(['raw' => $postData['message']], [], function($mail) use ($postData, $customer)
{
    $mail->subject($postData['subject']);

    $mail->to($customer->email, $customer->name);
});

Mail options

You may specify other options on the e-mail message such as any carbon copies or attachments as well., _(*15)

Set email subject

$mail->subject('Welcome User');

Set email "From" and "Reply-To" address / name

Instead use information stored in config file you can use array or string to set 'from' and 'reply-to' addresses / name., _(*16)

$address = ['webmaster@domain.tld', 'System Webmaster'];

// From
$mail->from($address);
// or
$mail->from('webmaster@domain.tld', 'System Webmaster');

// Reply To
$mail->reply($address);
// or
$mail->reply('webmaster@domain.tld', 'System Webmaster');

Set email receiver addresses / names.

You can define multiples recipients (name is optional)., _(*17)

// Add to
$mail->to('receiver1@domain.tld');
$mail->to('receiver2@domain.tld');

You can add multiples using array., _(*18)

// Build list
$list = [];
$list[] = 'receiver1@domain.tld';
$list[] = 'receiver2@domain.tld';

// List with names
$list = [];
$list[] = ['receiver1@domain.tld', 'Receiver 1'];
$list[] = ['receiver1@domain.tld', 'Receiver 2'];

// Add to
$mail->to($list);

Add carbon copy addresses / names

The cc option works like tooption even using multiples recipients., _(*19)

$mail->cc('carboncopy1@domain.tld', 'Copy Receiver 1');

// or

$mail->cc($list);

Add blind carbon copy addresses / names

The bcc option works like tooption even using multiples recipients., _(*20)

$mail->bcc('blindcarboncopy1@domain.tld', 'Blind Copy Receiver 1');

// or

$mail->bcc($list);

Attach files to email

You can add attachments., _(*21)

$mail->attach('/path/to/file1.png');
$mail->attach('/path/to/file2.png');

Debug Mode

In config file you can flag 'debug_mode' = true;, which can be helpful in testing your SMTP connections. It will write log files with server responses from each step in the email sending process., _(*22)

Or you can enable/disable debug mode just in some cases without edit config file., _(*23)

$mail->debug(true);

$mail->debug(false);

Change debug file path

By default the package uses default mako debug files but you can define another debug file location. Use the 'debugFilePath()' method to change file location., _(*24)

When you call this method you don't need to enable debug using $mail->debug(true)., _(*25)

$mail->debugFilePath('my/new/file/path');

Change server parameters

In config file you can define multiple connections, each of them with their own settings. The default connection settings used is defined in 'default' => 'primary' flag., _(*26)

Sometimes you may want to change which connection will be used. You can do this 'on-the-fly'., _(*27)

$mail->useConn('my_other_connection');

Also, you can define server parameters that are not included in config file., _(*28)

$mail->setConn('server_host_addr', 'server_conn_port', (null|'ssl'|'tls'), (true|false), 'my_auth_user_name', 'my_auth_password');

Change localhost domain name

You may want to change the origin of the HELO / EHLO request., _(*29)

Setting default value as "localhost" may cause email to be considered spam., _(*30)

$mail->setLocalhost('my.host.domain.name');

Credits

This package was build in top of Laravel SMTP class by swt83 - (https://github.com/swt83/php-laravel-smtp), _(*31)

Limitations

Just like original class, this package has some limitations. Please feel free to contribute to this project., _(*32)

• Does not support encryption.
• Does not support priority level.
• Does not keep connection open for spooling email sends.