locomotivemtl/charcoal-email

Email sending and queueing for Charcoal


README

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

Optional dependencies

👉 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' => [
        'recipient@example.com',
        '"Some guy" <someguy@example.com>',
        [
            'name'  => 'Other guy',
            'email' => 'otherguy@example.com'
        ]
    ],
    'bcc' => 'shadow@example.com'
    'from' => '"Company inc." <company.inc@example.com>',
    'reply_to' => [
        'name' => 'Jack CEO',
        'email' => 'jack@example.com'
    ],
    '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": "user@example.com",
        "smtp_password": "password",

        "default_from": "webproject@example.com",
        "default_reply_to": "webproject@example.com",
        "default_track": false,
        "default_log": true
    }
}

Service Provider

All email services can be quickly register 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.

1 \Charcoal\Email\Email.
2 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']).

3 \Charcoal\Email\EmailConfig.
4 \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 Build Status Runs code sniff check and unit tests. Auto-generates API documentation.
Scrutinizer Scrutinizer Code Quality Code quality checker. Also validates API documentation quality.
Coveralls Coverage Status Unit Tests code coverage.
Sensiolabs SensioLabsInsight Another code quality checker, focused on PHP.

Coding Style

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

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

Authors

License

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

Changelog

0.1

-Unreleased