Charcoal Email

Sending emails (with PHPMailer) and queue management.

How to install

The preferred (and only supported) way of installing charcoal-email is with composer:

★ composer require locomotivemtl/charcoal-email

Dependencies

• PHP 5.6+
  • PHP 7.3+ is highly recommended
• phpmailer/phpmailer
• locomotivemtl/charcoal-config
• locomotivemtl/charcoal-app

Optional dependencies

• pimple/pimple
  • Dependency injection Container (required for the Service Provider)

👉 All optional depedencies are required for development. All other development dependencies, which are optional when using charcoal-email in a project, are described in the Development section of this README file.

Usage

$email = $container['email'];
$email->setData([
    'campaign' => 'Campaign identifier'
    'to' => [
        '[email protected]',
        '"Some guy" <[email protected]>',
        [
            'name'  => 'Other guy',
            'email' => '[email protected]'
        ]
    ],
    'bcc' => '[email protected]'
    'from' => '"Company inc." <[email protected]>',
    'reply_to' => [
        'name' => 'Jack CEO',
        'email' => '[email protected]'
    ],
    'subject' => $this->translator->trans('Email subject'),
    'template_ident' => 'foo/email/default-email'
    'attachments' => [
        'foo/bar.pdf',
        'foo/baz.pdf'
    ]
]);
$email->send();

// Alternately, to send at a later date / use the queue system:
$email->queue('in 5 minutes');

Email Config

The entire email system can be configured from the main app config, in the email config key.

{
    "email": {
        "smtp": true,
        "smtp_hostname": "smtp.example.com",
        "smtp_port": 25,
        "smtp_security": "tls",
        "smtp_username": "[email protected]",
        "smtp_password": "password",

        "default_from": "[email protected]",
        "default_reply_to": "[email protected]",
        "default_track": false,
        "default_log": true
    }
}

Service Provider

All email services can be quickly registered to a (pimple) container with \Charcoal\Email\ServiceProvider\EmailServiceProvider.

Provided services:

Service	Type	Description
email	Email1	An email object (factory).
email/factory	FactoryInterface2	An email factory, to create email objects.

¹ \Charcoal\Email\Email.
² Charcoal\Factory\FactoryInterface.

Also available are the following helpers:

Helper Service	Type	Description
email/config	EmailConfig3	Email configuration.
email/view	ViewInterface4	The view object to render email templates ($container['view']).

³ \Charcoal\Email\EmailConfig.
⁴ \Charcoal\View\ViewInterface.

👉 For charcoal projects, simply add this provider to your config to enable:

{
  "service_providers": {
      "charcoal/email/service-provider/email": {}
  }
}

Service dependencies

For the email service provider to work properly, the following services are expected to e registerd on the same container:

• config
• view

Development

To install the development environment:

★ composer install --prefer-source

To run the scripts (phplint, phpcs and phpunit):

★ composer test

Development dependencies

• phpunit/phpunit
• squizlabs/php_codesniffer
• satooshi/php-coveralls

Continuous Integration

Service	Badge	Description
Travis		Runs code sniff check and unit tests. Auto-generates API documentation.
Scrutinizer		Code quality checker. Also validates API documentation quality.
Coveralls		Unit Tests code coverage.
Sensiolabs		Another code quality checker, focused on PHP.

Coding Style

The Charcoal-Email module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• Read the phpcs.xml file for all the details on code style.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Authors

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.