locomotivemtl/charcoal-contrib-communicator

Charcoal Communicator standardizes email communications destined for users and administors.

0.3.0 2022-02-17 20:34 UTC

This package is auto-updated.

Last update: 2024-11-18 03:16:31 UTC


README

License Latest Stable Version Code Quality Coverage Status Build Status

A Charcoal service for easy email template presets.

Table of Contents

Installation

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

$ composer require locomotivemtl/charcoal-contrib-communicator

Dependencies

Required

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

Development Dependencies

Coding Style

The charcoal-contrib-communicator 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.

Credits

License

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