locomotivemtl / charcoal-contrib-communicator
Charcoal Communicator standardizes email communications destined for users and administors.
Installs: 1 051
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 14
Forks: 0
Open Issues: 0
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
This package is auto-updated.
Last update: 2024-11-18 03:16:31 UTC
README
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
- 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
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 withcomposer phpcbf
.
Credits
License
Charcoal is licensed under the MIT license. See LICENSE for details.