PHPackages locomotivemtl/charcoal-contrib-communicator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Mail & Notifications](/categories/mail) 4. / 5. locomotivemtl/charcoal-contrib-communicator ActiveLibrary[Mail & Notifications](/categories/mail) locomotivemtl/charcoal-contrib-communicator =========================================== Charcoal Communicator standardizes email communications destined for users and administors. 1.0.0(5mo ago)11.2kMITPHPPHP >=5.6.0 || >=7.0 || >=8.0 Since Jul 19Pushed 5mo ago12 watchersCompare [ Source](https://github.com/locomotivemtl/charcoal-contrib-communicator)[ Packagist](https://packagist.org/packages/locomotivemtl/charcoal-contrib-communicator)[ Docs](https://locomotivemtl.github.io/charcoal-contrib-communicator/)[ RSS](/packages/locomotivemtl-charcoal-contrib-communicator/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (4)Dependencies (4)Versions (7)Used By (0) Charcoal Communicator ===================== [](#charcoal-communicator) [![License](https://camo.githubusercontent.com/7a4caad811dfa13287f8a5f3e07b1f0ce0316bdb32ccbbb7de4ff3dcf024740e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c6f636f6d6f746976656d746c2f63686172636f616c2d636f6e747269622d636f6d6d756e696361746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/locomotivemtl/charcoal-contrib-communicator)[![Latest Stable Version](https://camo.githubusercontent.com/97def7275850cd0b480b958c5378eeecb0f70d724b90e7d793924f6b83301a0d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c6f636f6d6f746976656d746c2f63686172636f616c2d636f6e747269622d636f6d6d756e696361746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/locomotivemtl/charcoal-contrib-communicator)[![Code Quality](https://camo.githubusercontent.com/a730069b8d3a93ba7d8b9dd7dd5a5354b6c3ad8e9c6c19237b2ddaaf27358bb5/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f6c6f636f6d6f746976656d746c2f63686172636f616c2d636f6e747269622d636f6d6d756e696361746f722e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-contrib-communicator/)[![Coverage Status](https://camo.githubusercontent.com/c923a9d9cff912b8d6acf3975fac6a876962cfc4fa7aaafe91141d3c53bf06d8/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6c6f636f6d6f746976656d746c2f63686172636f616c2d636f6e747269622d636f6d6d756e696361746f722e7376673f7374796c653d666c61742d737175617265)](https://coveralls.io/r/locomotivemtl/charcoal-contrib-communicator)[![Build Status](https://camo.githubusercontent.com/283b9777a610ff6157999f5b99ca1e8e1baa2b10fdd76ceea02cea56eeb1f420/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f636f6d2f6c6f636f6d6f746976656d746c2f63686172636f616c2d636f6e747269622d636f6d6d756e696361746f722e7376673f7374796c653d666c61742d737175617265)](https://app.travis-ci.com/github/locomotivemtl/charcoal-contrib-communicator) A [Charcoal](https://packagist.org/packages/locomotivemtl/charcoal-app) service for easy email template presets. Table of Contents ----------------- [](#table-of-contents) - [Installation](#installation) - [Dependencies](#dependencies) - [Service Provider](#service-provider) - [Parameters](#parameters) - [Services](#services) - [Configuration](#configuration) - [Usage](#usage) - [Development](#development) - [API Documentation](#api-documentation) - [Development Dependencies](#development-dependencies) - [Coding Style](#coding-style) - [Credits](#credits) - [License](#license) Installation ------------ [](#installation) The preferred (and only supported) method is with Composer: ``` $ composer require locomotivemtl/charcoal-contrib-communicator ``` ### Dependencies [](#dependencies) #### Required [](#required) - [**PHP 5.6+**](https://php.net): *PHP 7* is recommended. - [**locomotivemtl/charcoal-email**](https://packagist.org/packages/locomotivemtl/charcoal-email): ^0.3 Service Provider ---------------- [](#service-provider) ### Services [](#services) - **communicator**: Instance of `Charcoal\Communicator\Communicator`. Configuration ------------- [](#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": "See the entry on Charcoal" } } } } } ``` See [`communicator.sample.json`](blob/master/config/communicator.sample.json)for a thorough example. Usage ----- [](#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 ----------- [](#development) To install the development environment: ``` $ composer install ``` To run the scripts (phplint, phpcs, and phpunit): ``` $ composer test ``` ### API Documentation [](#api-documentation) - The auto-generated `phpDocumentor` API documentation is available at: - The auto-generated `apigen` API documentation is available at: [https://codedoc.pub/locomotivemtl/charcoal-contrib-communicator/master/](https://codedoc.pub/locomotivemtl/charcoal-contrib-communicator/master/index.html) ### Development Dependencies [](#development-dependencies) - [php-coveralls/php-coveralls](https://packagist.org/packages/php-coveralls/php-coveralls) - [phpunit/phpunit](https://packagist.org/packages/phpunit/phpunit) - [squizlabs/php\_codesniffer](https://packagist.org/packages/squizlabs/php_codesniffer) ### Coding Style [](#coding-style) The charcoal-contrib-communicator module follows the Charcoal coding-style: - [*PSR-1*](https://www.php-fig.org/psr/psr-1/) - [*PSR-2*](https://www.php-fig.org/psr/psr-2/) - [*PSR-4*](https://www.php-fig.org/psr/psr-4/), autoloading is therefore provided by *Composer*. - [*phpDocumentor*](http://phpdoc.org/) comments. - [phpcs.xml.dist](phpcs.xml.dist) and [.editorconfig](.editorconfig) for coding standards. > Coding style validation / enforcement can be performed with `composer phpcs`. An auto-fixer is also available with `composer phpcbf`. Credits ------- [](#credits) - [Locomotive](https://locomotive.ca/) License ------- [](#license) Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details. ### Health Score 46 — FairBetter than 93% of packages Maintenance71 Regular maintenance activity Popularity17 Limited adoption so far Community17 Small or concentrated contributor base Maturity68 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~774 days Total 4 Last Release 165d ago Major Versions 0.3.0 → 1.0.02025-11-28 PHP version history (2 changes)0.1.0PHP >=5.6.0 || >=7.0 1.0.0PHP >=5.6.0 || >=7.0 || >=8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/cfb071c0ff7ce9500c528a003a2c53124248debc3e5bf367c17f89f5e6136125?d=identicon)[mducharme](/maintainers/mducharme) ![](https://www.gravatar.com/avatar/0a4f39523b4b2837562ba0848a0327b8d340118d1ba87cb0f5d59b1d5cb6beba?d=identicon)[mcaskill](/maintainers/mcaskill) ![](https://www.gravatar.com/avatar/b806b936695bdb12bf55e0e805bdaef15507502a07a16e34d43c5aad17390468?d=identicon)[dominiclord](/maintainers/dominiclord) --- Top Contributors [![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (9 commits)")[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (9 commits)")[![MouseEatsCat](https://avatars.githubusercontent.com/u/9273580?v=4)](https://github.com/MouseEatsCat "MouseEatsCat (3 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (1 commits)") --- Tags charcoal ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/locomotivemtl-charcoal-contrib-communicator/health.svg) ``` [![Health](https://phpackages.com/badges/locomotivemtl-charcoal-contrib-communicator/health.svg)](https://phpackages.com/packages/locomotivemtl-charcoal-contrib-communicator) ``` ### Alternatives [tijsverkoyen/css-to-inline-styles CssToInlineStyles is a class that enables you to convert HTML-pages/files into HTML-pages/files with inline styles. This is very useful when you're sending emails. 5.8k505.3M227](/packages/tijsverkoyen-css-to-inline-styles)[minishlink/web-push Web Push library for PHP 1.9k12.0M53](/packages/minishlink-web-push)[laravel-notification-channels/twilio Provides Twilio notification channel for Laravel 2587.7M12](/packages/laravel-notification-channels-twilio)[spatie/url-signer Generate a url with an expiration date and signature to prevent unauthorized access 4422.3M16](/packages/spatie-url-signer)[mattketmo/email-checker Throwaway email detection library 2742.0M5](/packages/mattketmo-email-checker)[netflie/laravel-notification-whatsapp Laravel notification driver for WhatsApp 176173.9k](/packages/netflie-laravel-notification-whatsapp) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)