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.6.0(2mo ago)06.4k—0%[7 issues](https://github.com/Mistralys/mailcode/issues)1MITPHPPHP >=8.4CI passing

Since Mar 5Pushed 2mo ago4 watchersCompare

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

READMEChangelog (10)Dependencies (8)Versions (83)Used By (1)

Mailcode — PHP Syntax Parser for Email Preprocessing
====================================================

[](#mailcode--php-syntax-parser-for-email-preprocessing)

**A backend-agnostic preprocessor command language for email templates.** Mailcode provides a unified, verbose syntax for variables, conditionals, loops, and formatting commands that can be translated into target preprocessor languages like **Apache Velocity** or **Hubspot HubL**.

[![PHP](https://camo.githubusercontent.com/c3362351d1264fd924675776c4f8307bf5f229fa15cbbd49d020909278dadb3a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344372e342d626c7565)](https://www.php.net/)[![License](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e)](LICENSE)

---

Why Mailcode Exists
-------------------

[](#why-mailcode-exists)

Email template systems often depend on a specific backend preprocessor (Velocity, HubL, etc.). Mailcode **decouples the authoring experience** from the backend implementation: authors write in one readable syntax, and the library translates it to whatever the backend requires. This makes email editor interfaces portable across different mailing platforms.

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

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

Mailcode is intentionally verbose — every command reads like a sentence, making templates self-documenting and easy to review without knowing the backend.

**Display a variable value**

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

```

**Format a date, a number, or a price**

```
Ordered on: {showdate: $ORDER.DATE "d.m.Y"}
Items in cart: {shownumber: $CART.ITEMS "1,000"}
Total: {showprice: $ORDER.TOTAL}

```

**Conditional logic with readable subtypes**

```
{if variable: $CUSTOMER.STATUS == "premium"}
    You have free shipping on this order.
{elseif list-contains: $ORDER.TAGS "fragile"}
    Please handle with care.
{else}
    Standard shipping rates apply.
{end}

```

**Loop through a list variable**

```
Your ordered products:

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

```

**Build tracking URLs with automatic encoding**

```
{showurl: "header-cta"}
    https://example.com/offers?ref={showvar: $CUSTOMER.ID urlencode:}&domain={showvar: $CUSTOMER.DOMAIN idnencode: urlencode:}
{showurl}

```

All of the above translates automatically to Apache Velocity or HubL — no template changes required.

---

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);
```

Folder Overview
---------------

[](#folder-overview)

FolderPurpose**`src/`**All library source code. Entry point: `Mailcode.php`.**`src/Mailcode/Commands/`**Command definitions — the 20+ command types (show, if, for, set, etc.) and their type hierarchy.**`src/Mailcode/Parser/`**String parsing engine: regex matching, statement tokenization, safeguard system, and formatting pipeline.**`src/Mailcode/Translator/`**Output syntax translators (Apache Velocity, HubL) with per-command translation classes.**`src/Mailcode/Factory/`**Programmatic command creation organized into command sets (show, set, if, elseif, misc, var).**`src/Mailcode/Variables/`**Variable parsing and representation (`$PATH.NAME` pattern).**`src/Mailcode/Traits/`**Reusable validation and capability traits for commands (encoding, keywords, search terms, etc.).**`src/Mailcode/Interfaces/`**Corresponding interfaces for the traits system.**`src/Mailcode/Date/`**Date format validation and character definitions.**`src/Mailcode/Number/`**Number and currency formatting configuration.**`src/Mailcode/Decrypt/`**Decryption key name management for encrypted variable values.**`src/Mailcode/Collection/`**Command collection utilities: nesting validation, type filtering, error tracking.**`css/`**Stylesheets for HTML syntax highlighting of commands.**`localization/`**Translation files (German locale included).**`tests/`**PHPUnit test suites — extensive coverage across all subsystems.**`tools/`**Browser-based utilities (syntax translator, highlighter, phone country extractor).**`docs/`**Documentation: user guides, architecture reference, PHPDoc config.Public API / Entry Points
-------------------------

[](#public-api--entry-points)

All interactions start through the **`Mailcode`** class or the **`Mailcode_Factory`** static API:

Entry PointMethodReturns**Parse commands**`Mailcode::create()->parseString($text)``Mailcode_Collection`**Safeguard text**`Mailcode::create()->createSafeguard($text)``Mailcode_Parser_Safeguard`**Find variables**`Mailcode::create()->findVariables($text)``Mailcode_Variables_Collection_Regular`**Translate syntax**`Mailcode::create()->createTranslator()``Mailcode_Translator`**Preprocess**`Mailcode::create()->createPreProcessor($text)``Mailcode_PreProcessor`**CSS styling**`Mailcode::create()->createStyler()``Mailcode_Styler`**Create commands**`Mailcode_Factory::show()`, `::set()`, `::if()`, `::elseIf()`, `::misc()`, `::var()`Command set instances**Render commands**`Mailcode_Factory::createRenderer()``Mailcode_Renderer`**Date format info**`Mailcode_Factory::createDateInfo()``Mailcode_Date_FormatInfo`Documentation Index
-------------------

[](#documentation-index)

DocumentDescription[Usage Guide](docs/user-guide/usage-guide.md)Full syntax reference, all commands, encoding, safeguarding, formatting, and translation examples.[Architecture](docs/architecture.md)Internal class hierarchy, pipeline diagram, subsystem descriptions, and dependency graph.[Apache Velocity Translation](docs/user-guide/translate-apache-velocity.md)Velocity-specific translation details, required tools, and configuration.[HubL Translation](docs/user-guide/translate-hubl.md)Hubspot HubL translation support and limitations.[Changelog](changelog.md)Version history and breaking changes.Supported Commands (Summary)
----------------------------

[](#supported-commands-summary)

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

[](#translation-targets)

SyntaxCoverage**Apache Velocity**Full — all commands translated**Hubspot HubL**Partial — `showvar`, `showencoded`, `showurl`, `setvar`, subset of `if`/`elseif`License
-------

[](#license)

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

###  Health Score

57

—

FairBetter than 98% of packages

Maintenance87

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity89

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 95.8% 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 ~91 days

Total

80

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 (985 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

[j0k3r/graby

Graby helps you extract article content from web pages

384349.6k1](/packages/j0k3r-graby)[jkphl/micrometa

A meta parser for extracting micro information out of web documents, currently supporting Microformats 1+2, HTML Microdata, RDFa Lite 1.1 and JSON-LD

114163.8k1](/packages/jkphl-micrometa)[skymeyer/vatsimphp

VATSIM data parser

3217.9k1](/packages/skymeyer-vatsimphp)

PHPackages © 2026

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