locomotivemtl/charcoal-email

Email sending and queueing for Charcoal

Charcoal Email

Sending emails (with PHPMailer) and queue management., _(*1)

How to install

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

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

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

{
    "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 registered to a (pimple) container with \Charcoal\Email\ServiceProvider\EmailServiceProvider., _(*5)

Provided services:, _(*6)

¹ \Charcoal\Email\Email.
² Charcoal\Factory\FactoryInterface.
, _(*7)

Also available are the following helpers:, _(*8)

³ \Charcoal\Email\EmailConfig.
⁴ \Charcoal\View\ViewInterface.
, _(*9)

👉 For charcoal projects, simply add this provider to your config to enable:, _(*10)

{
    "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:, _(*11)

• config
• view

Development

To install the development environment:, _(*12)

★ composer install --prefer-source

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

★ 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:, _(*14)

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

Authors

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details., _(*16)