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

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' => [
        '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 registered to a (pimple) container with \Charcoal\Email\ServiceProvider\EmailServiceProvider.

Provided services:

Service	Type	Description
email	`Email`¹	An email object (factory).
email/factory	`FactoryInterface`²	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	`EmailConfig`³	Email configuration.
email/view	`ViewInterface`⁴	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.

locomotivemtl / charcoal-email

Maintainers

Details