PHPackages                             mistralys/mailcode - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. mistralys/mailcode

ActiveLibrary[Parsing & Serialization](/categories/parsing)

mistralys/mailcode
==================

Mailcode syntax parsing library for PHP

3.7.2(2mo ago)17.2k↑421.1%[5 issues](https://github.com/Mistralys/mailcode/issues)1MITPHPPHP >=8.4CI failing

Since Mar 5Pushed 3mo ago4 watchersCompare

[ Source](https://github.com/Mistralys/mailcode)[ Packagist](https://packagist.org/packages/mistralys/mailcode)[ RSS](/packages/mistralys-mailcode/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (10)Dependencies (24)Versions (86)Used By (1)

Mailcode
========

[](#mailcode)

**A backend-agnostic preprocessor command language for email templates.**

What Is Mailcode?
-----------------

[](#what-is-mailcode)

Email template systems often lock you into a specific backend preprocessor — Velocity, HubL, or whatever your mailing platform speaks. Mailcode frees you from that. Authors write in one readable, verbose syntax, and the library translates it into whatever the backend requires. Your email editor becomes portable across platforms without rewriting a single template.

Features
--------

[](#features)

- **One syntax, multiple backends** — Write once, translate to Apache Velocity or Hubspot HubL automatically.
- **Self-documenting templates** — Commands read like sentences (`{if variable: $STATUS == "premium"}`), making reviews easy for non-developers.
- **Rich command set** — Variables, conditionals (16 subtypes), loops, date/number/price formatting, phone formatting, URL encoding, snippets, and more.
- **Safeguard system** — Protect Mailcode commands while you process surrounding HTML/text freely, then restore them intact.
- **Programmatic command creation** — Build commands in PHP via a fluent factory API, not just by parsing strings.
- **Syntax highlighting** — Render commands with CSS-styled HTML for visual editors.
- **Validation built in** — Parse results include detailed error reporting; no silent failures.

Requirements
------------

[](#requirements)

- PHP **>= 8.4**
- Composer
- `ext-json`

Quick Start
-----------

[](#quick-start)

```
composer require mistralys/mailcode
```

```
use Mailcode\Mailcode;
use AppUtils\FileHelper\FolderInfo;

// Required: set a cache folder for class discovery
Mailcode::setCacheFolder(FolderInfo::factory('/path/to/cache'));

// Parse a string containing Mailcode commands
$collection = Mailcode::create()->parseString('{showvar: $CUSTOMER.NAME}');

// Safeguard commands during text processing
$safeguard = Mailcode::create()->createSafeguard($htmlContent);
$safe = $safeguard->makeSafe();
// ... process the text freely ...
$result = $safeguard->makeWhole($safe);

// Translate to Apache Velocity
$velocity = Mailcode::create()->createTranslator()->createApacheVelocity();
$output = $velocity->translateSafeguard($safeguard);
```

Syntax at a Glance
------------------

[](#syntax-at-a-glance)

```
Hello {showvar: $CUSTOMER.FIRSTNAME}, your order is ready.

Ordered on: {showdate: $ORDER.DATE "d.m.Y"}
Total: {showprice: $ORDER.TOTAL}

{if variable: $CUSTOMER.STATUS == "premium"}
    You have free shipping on this order.
{end}

{for: $PRODUCT in: $USER_LIST_PRODUCTS}
- {showvar: $PRODUCT.NAME}: {showprice: $PRODUCT.PRICE}
{end}

```

Supported Commands
------------------

[](#supported-commands)

CategoryCommands**Display**`{showvar}`, `{showdate}`, `{shownumber}`, `{showprice}`, `{showsnippet}`, `{showencoded}`, `{showphone}`, `{showurl}`**Variables**`{setvar}` (string, arithmetic, list counting)**Conditionals**`{if}`, `{elseif}`, `{else}`, `{end}` — 16 subtypes (variable, contains, empty, list-contains, begins-with, bigger-than, etc.)**Loops**`{for}`, `{break}`**Formatting**`{mono}`, `{code}`**Meta**`{comment}`Translation Targets
-------------------

[](#translation-targets)

SyntaxCoverage**Apache Velocity**Full — all commands translated**Hubspot HubL**Partial — `{break}` and `{showsnippet}` not supportedLearn More
----------

[](#learn-more)

ResourceDescription[Usage Guide](docs/user-guide/mailcode-documentation.md)Full syntax reference, all commands, encoding, safeguarding, and translation examples[Apache Velocity Translation](docs/user-guide/translate-apache-velocity.md)Velocity-specific translation details and configuration[HubL Translation](docs/user-guide/translate-hubl.md)Hubspot HubL translation support and limitations[Changelog](changelog.md)Version history and breaking changesLicense
-------

[](#license)

[MIT](LICENSE) — Sebastian Mordziol / [Mistralys](https://github.com/Mistralys)

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance63

Regular maintenance activity

Popularity25

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity90

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 95.9% of commits — single point of failure

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 ~27 days

Recently: every ~97 days

Total

83

Last Release

66d ago

Major Versions

1.9.1 → 2.0.02021-03-16

2.1.7 → 3.0.02022-03-03

PHP version history (3 changes)2.1.7PHP >=7.3

3.0.0PHP >=7.4

3.6.0PHP >=8.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8895528?v=4)[Mistralys](/maintainers/Mistralys)[@Mistralys](https://github.com/Mistralys)

---

Top Contributors

[![Mistralys](https://avatars.githubusercontent.com/u/8895528?v=4)](https://github.com/Mistralys "Mistralys (1002 commits)")[![olafboecker](https://avatars.githubusercontent.com/u/194353743?v=4)](https://github.com/olafboecker "olafboecker (40 commits)")[![dstorch-ionos](https://avatars.githubusercontent.com/u/153072168?v=4)](https://github.com/dstorch-ionos "dstorch-ionos (3 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mistralys-mailcode/health.svg)

```
[![Health](https://phpackages.com/badges/mistralys-mailcode/health.svg)](https://phpackages.com/packages/mistralys-mailcode)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k39.6k](/packages/matomo-matomo)[craftcms/cms

Craft CMS

3.6k3.7M3.3k](/packages/craftcms-cms)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k19](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

86337.5k](/packages/flow-php-flow)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.8M650](/packages/shopware-core)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45844.8k1](/packages/pressbooks-pressbooks)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)