johnnyxlemonade / email-generator
A component-based HTML email generator for Lemonade Framework.
Package info
github.com/johnnyxlemonade/email-generator
pkg:composer/johnnyxlemonade/email-generator
Requires
- php: >=8.3 <8.6
- johnnyxlemonade/framework: dev-main
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.94
- phpstan/phpstan: 2.3.0
- phpstan/phpstan-strict-rules: 2.1.0
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 16:21:28 UTC
README
johnnyxlemonade/email-generator provides component-based HTML email generation
for Lemonade Framework applications. It integrates with the framework container,
configuration and localization services and supports both HTTP and CLI use.
Applications compose immutable documents from typed components, formatted text and translations. The package renders HTML with table-based layouts, inline CSS, responsive columns and Outlook fallback markup.
Installation
The package requires PHP >=8.3 <8.6 and
johnnyxlemonade/framework:dev-main.
composer require johnnyxlemonade/email-generator:dev-main
Append the provider to your existing app/Config/Providers.yaml:
module: providers config: providers: - Lemonade\EmailGenerator\EmailServiceProvider
Include Providers in the shared section of app/Config/Config.yaml to make
the service available to both HTTP and CLI entrypoints:
shared: - Providers
The standard framework bootstrap registers localization. Custom framework
provider lists must retain LocalizationServiceProvider; the email provider
uses its existing translator and default locale configuration.
Usage
Inject Lemonade\EmailGenerator\EmailGenerator into an application service or
command and use it to create a document:
$html = $emails ->create(locale: 'en', title: 'Welcome', preheader: 'Your account is ready.') ->heading('Welcome') ->text('Thank you for signing up.') ->button('Activate account', 'https://example.com/activate') ->render();
Every fluent method returns a new document. Retain its return value when calling
methods separately. title sets the HTML document title, not a MIME subject.
Built-in components include Heading, Text, Image, Button, ButtonGroup,
Steps, BulletList, Table, Divider, Spacer, Group, Columns, Badge,
KeyValue, Quote, Signature, AddressBlock and AttachmentList.
Use RichText and TextRun for inline formatting, Translation for framework
catalog entries, and CompositionInterface for reusable groups of components
without renderer registration. Signature accepts a Contact and optional
ImageSource; AddressBlock accepts an Address; AttachmentList accepts
validated AttachmentItem metadata. These immutable value objects
own their data validation and normalization.
See the API reference for component options, nesting, immutable documents, configuration, localization and validation.
Package boundaries
- Lemonade Framework owns the container, application bootstrap, configuration and translation services.
- Email Generator owns document composition, content validation and HTML rendering.
- The host application owns business content, public image URLs, MIME messages, delivery, physical attachments and queues.
The public API accepts typed content and options. Text and attributes are escaped; URLs must be absolute HTTP(S). Raw HTML, arbitrary CSS and custom renderer configuration are not part of the application API.
Generated markup includes Outlook fallbacks, but appearance depends on the email client. Automated tests verify markup and fixtures; they do not verify rendering inside Outlook or Gmail.
Examples
generate.php builds local previews from the matching
readable sources in examples/php/. They cover complete email
scenarios plus minimal standalone examples of every current component and
built-in composition.
composer examples
The examples include versioned PHP sources, application configuration and
translation catalogs. Generated HTML is written to the ignored examples/html/
directory. See the
example README for the directory layout, catalog and layout
notes.
Development and QA
From the package root, install dependencies and run:
composer install composer qa
composer qa runs PHP CS Fixer, PHPStan and PHPUnit. GitHub Actions cover
coding standards,
static analysis and
tests on PHP 8.3–8.5.