locomotivemtl/charcoal-contrib-communicator

Charcoal Communicator standardizes email communications destined for users and administors.

0.3.0 2022-02-17 20:34 UTC

Requires

• php: >=5.6.0 || >=7.0
• locomotivemtl/charcoal-email: ~0.3

Requires (Dev)

• php-coveralls/php-coveralls: ^2.0
• phpunit/phpunit: ^5.7 || ^6.5
• squizlabs/php_codesniffer: ^3.0

MIT

• Locomotive

• charcoal

README

A Charcoal service for easy email template presets.

Table of Contents

• Installation
  • Dependencies
• Service Provider
  • Parameters
  • Services
• Configuration
• Usage
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-communicator

Dependencies

Required

• PHP 5.6+: PHP 7 is recommended.
• locomotivemtl/charcoal-email: ^0.3

Service Provider

Services

• communicator: Instance of Charcoal\Communicator\Communicator.

Configuration

The Communicator uses scenarios (such as a enquiry confirmation) grouped into channels (such as for a user or an administrator). These can be defined from the application configset:

{
    "communicator": {
        "user": {
            "contact": {
                "log": true,
                "campaign": "",
                "subject": "Contact Us Confirmation",
                "template_ident": "communicator/email/default",
                "template_data": {
                    "message": "Thank you {{ form_data.full_name }} for your interest in our company! We received your request for information and will contact you as soon as we can."
                }
            }
        },
        "admin": {
            "contact": {
                "log": true,
                "campaign": "",
                "subject": "Contact Us Notification",
                "template_ident": "communicator/email/default",
                "template_data": {
                    "title": "New Contact form submission from {{ form_data.full_name }}",
                    "message": "{{ form_data.full_name }} would like information concerning {{ form_data.category }}.",
                    "charcoal": "<a href=\"{{ template_data.charcoal_url }}\"><b>See the entry on Charcoal<b></a>"
                }
            }
        }
    }
}

See communicator.sample.json for a thorough example.

Usage

The Communicator can prepare and send emails based on the selected scenario, channel, and any custom data:

/**
 * @var \Charcoal\Communicator\Communicator $communicator
 * @var \App\Model\Contact\Entry            $entry
 */

$formData = [
    'full_name'     => $entry['full_name'],
    'business_name' => $entry['business_name'],
    'email_address' => $entry['email_address'],
    'category'      => transform($entry['category_id'], function ($categoryId) {
        // Fetch name of Category object from Category ID.
    }),
    'message'       => $entry['message'],
];

$communicator->setFormData($formData);

$communicator->setTo([
    'email' => $entry['email_address'],
    'name'  => $entry['full_name'],
]);

$emailData = [
    'template_data' => [
        'entry'        => $formData,
        'charcoal_url' => build_admin_url('object/edit', [
            'obj_type' => Entry::objType(),
            'obj_id'   => $entry['id'],
        ]),
    ],
];

/** @var bool */
$sent = $communicator->send('contact', 'user', $emailData);

By default, the Communicator will use the email address from email.default_from from your application configset.

Development

To install the development environment:

$ composer install

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

$ composer test

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-contrib-communicator/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-contrib-communicator/master/

Development Dependencies

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

Coding Style

The charcoal-contrib-communicator module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

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

Credits

• Locomotive

License

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