Download the PHP package mistralys/mailcode without Composer

PHP Mailcode Syntax parser

Mailcode is a preprocessor command syntax created for use in emailings.

It aims to be easy to use by authors, and usable in a number of popular web formats, from plain text to HTML and XML. The Mailcode syntax is verbose by design, without shorthand notations, for both better readability and performance.

It has been developed to support interchangeable backend preprocessor syntaxes, to unify these into a single language.

The syntax

Base Structure

All commands follow the same structure.

Parameterless:

With parameters:

The subtype can switch between modes of the same command.

Toggleable flags to enable/disable features:

Named parameters:

Escaping special characters

Double quotes

String literals are expected to be quoted using double quotes ("). To use double quotes within a string literal, it can be escaped using a backslash (\):

Note: When using the Factory to create commands, this is done automatically.

Curly braces

To use curly braces in a document, or in string literals, they can be escaped:

Supported commands

Display variable values

Display a date and time

Using the default date and time settings for the current locale:

With a custom date/time format:

Note: Also see the section on date formats for details on how to specify date and time.

If no variable is specified, it is assumed that the current date and time should be used:

With a specific time zone:

If no time zone is specified, the default PHP time zone is used (this is typically UTC unless the server is configured differently).

It is possible to set the default time zone globally for the command, separately from the native PHP time zone:

This will make all showdate commands use Europe/Paris, unless a specific time zone is specified explicitly in a command.

Display a formatted number

To specify the format for the number, write the number 1000 the way you would like to have it formatted. This will be applied to the values accordingly.

This will use commas as a thousand separator, a dot for the decimals, and two decimal positions.

For example, 10 will be displayed as 10.00, and 5120.4 as 5,120.40.

Zero-Padding

Zero-padding is specified by appending the required number length like this:

The number of hashes determines the target length of the number. This example will add a zero-padding of 2, meaning a 5 will be shown as 05.

Absolute numbers

When working with negative numbers, you can use the absolute: keyword to ensure that the minus sign is not shown.

Display a price

A number can be formatted to be displayed as a price with localized formatting and currency symbol/name.

With default settings (USD):

With a specific currency, as string or variable:

For a specific region, as string or variable:

As an absolute number:

Use the currency name (e.g. "EUR") instead of the symbol:

Display a text snippet

Display a raw text snippet. Newlines are converted to HTML <br> tags automatically.

To disable the <br> tags, use the nohtml: keyword:

A namespace can be specified if the target snippet should not be loaded from the global namespace:

Display a URL with or without tracking

URLs may contain variables, or even logic commands. The showurl command makes it possible to integrate these into tracking URLs, by rendering the final URL on the target language level.

Adding tracking

Consider the following URL:

To make this trackable, use the following command:

NOTE: The command must be closed with {showurl}, not {end}.

On the target language level (e.g. Apache Velocity), this will evaluate the result of the if command first, to resolve the final URL. This can then be easily used in any tracking implementation, which also needs to be implemented on the target language level.

Tracking IDs

The tracking ID is used to identify the location of the link in the document, e.g. header-image. If it is omitted or empty, an automatic ID will be generated.

The minimum version of the command looks like this:

The default generated tracking ID follows this scheme: link-001, with a link counter that is unique for the whole request. A custom ID generator can be registered like this:

Adding query parameters

The command allows specifying additional query parameters that should be added to the target URL, like UTM parameters or the like.

Example command:

Resulting example tracking URL:

Disabling the tracking

The tracking can be disabled with the no-tracking: keyword, in which case only the evaluated URL is used. Additional query parameters can still be added.

Resulting URL:

Phone numbers in URLs

The {showphone} command can convert a phone number in a country-specific or international formatted style to the E164 format required for tel: URLs.

Whenever you wish to add a phone link, use this:

This will convert the phone number to the expected format.

Set a variable

String value

Arithmetic operation

Basic arithmetic operations can be used, provided the target language supports these. They are typically passed on directly through the translator, unless it has special logic to convert them.

Counting lists

The count parameter allows specifying a list variable to count the records of, and store the amount in the target variable.

Omitting the = sign

The equal sign is implied, so it can be omitted.

IF conditionals

Variable-based conditions

Checking for empty or non-empty variables

Checking if a variable does not exist, or is empty:

Checking if a variable exists and is not empty:

Searching for substrings

Checking if a variable value contains a string:

Case-insensitive search:

Searching for multiple terms (applied if any of the terms is found):

Matching a variable value if it does NOT contain any of the search terms:

Searching lists by partial matches

If a variable contains several records, it is possible to search through a property in all records, without having to use a loop:

This will search in the NAME property of all products for the specified search term.

The command otherwise behaves like the contains command, with the same options.

Case-insensitive search:

Negating the search, applying it only if the search terms are not found:

Searching lists by regular expressions

The list-contains can be switched to regex mode with the regex: keyword:

NOTE: This can be combined with the insensitive: keyword to make the regular expression case-insensitive.

Regular expressions may use curly braces when defining quantifiers, e.g. {1,5}. This is a special case where you do not have to escape the braces. The parser will recognize these braces so the regex stays readable.

These commands are both valid:

Searching lists by exact matches

Using regular expressions allows searching for exact matches by using the beginning and end anchors \A and \Z, but this is unwieldy and not exactly readable. The list-equals command does exactly this.

This will match only if an entry in the list is an exact match for "Search".

It can be combined with the insensitive: keyword to search for the full search term, but in a case-insensitive way.

Searching lists by beginning or end

Checking if a variable value starts with a specific string:

Or checking if it ends with a specific string:

Both can be made case-insensitive:

Numeric comparisons

Checking if a variable value is bigger than a specific number:

Or checking if it is smaller:

Or checking for an exact match:

Freeform conditions:

Without subtype, the IF condition is not validated, and will be passed through as-is to the translation backend.

AND and OR combinations

Several conditions can be combined within the same command using the and: and or: keywords. Either can be used, but not both within the same command. Subtypes can be mixed at will.

Using AND:

Using OR:

Loops

Breaking out of loops

Stopping at a specific iteration

The break-at parameter allows stopping the loop at a specific loop iteration count (0-based).

Comments

Comments may be added to document things. Whether they are used when translated to a specific preprocessor language depends on the translator. In general, the comments are converted to the target language.

NOTE: Comments can contain special characters, except other Mailcode commands or texts that can be mistaken for commands (which use the brackets {}).

Encoding and decoding values

URL encoding

To URL encode a variable value:

The opposite is also possible:

IDN encoding

To encode a variable value to IDN:

The opposite is also possible:

Encrypted values

Encrypted values can be decrypted at render time in the target backend system. This is intended to be used with key names, which uniquely identify the relevant encryption key to use to decrypt the values on the backend side.

To use the backend system's default encryption key name, add the parameter with an empty value:

To use a specific key name:

Default key names

It is also possible to set a default key name that will be automatically used for all commands with an empty decrypt parameter:

After this method is called, the following commands are functionally equivalent:

Integrated preprocessing

Mailcode is a preprocessor language meant to be interpreted by a preprocessor service, but some commands are made to be preprocessed natively by Mailcode itself. One example is the mono command, which applies monospace formatting to text.

The preprocessing is optional and can be done with the specialized PreProcessor class.

NOTE: When translating to an output syntax like Apache Velocity, the default behavior is to strip out leftover preprocessor commands, so there can be no Mailcode commands in the translated text.

Working with the PreProcessor

The PreProcessor is very easy to use: feed it a string with Mailcode commands, and all commands that support pre-processing will be rendered. After this, the resulting string can be passed into a safeguard instance or parsed to fetch the commands.

NOTE: While the preprocessing can be done after safeguarding a text, it is recommended to do it beforehand, to avoid the overhead of unnecessarily parsing the commands. Also, these commands may actually generate new Mailcode syntax to parse.

Format a text as code

The resulting pre-processed text will look like this:

To create a <pre> tag, add the multiline keyword:

This gives the following pre-processed text:

Working with commands

Closing, opening and sibling commands

Commands like for loops, and if statements that have a closing command and are closed using the {end} command support accessing their siblings, and respective opening and closing commands.

For example, the closing command of an IF statement has the getOpeningCommand() method, which returns the IF command that it closes, and vice versa. If command structures with elseif and else commands allow traversing the whole list of sibling commands.

This makes it easy to work with complex command structures.

Date formats

Supported formatting characters

The ShowDate command uses formatting characters that are compatible with PHP's date formatting functions, but only a subset of these are allowed.

• d Day number, with leading zeros
• j Day number, without leading zeros
• m Month number, with leading zeros
• n Month number, without leading zeros
• y Year, with two digits
• Y Year, with four digits
• H Hour, 24-hour format, with leading zeros
• G Hour, 24-hour format, without leading zeros
• h Hour, 12-hour format, with leading zeros
• g Hour, 12-hour format, without leading zeros
• a AM/PM marker, lowercase
• i Minutes, with leading zeros
• s Seconds, with leading zeros
• v Milliseconds
• e Time zone identifier, e.g. "CET", "Europe/Paris"

Additionally, the following punctuation characters may be used:

• . Dot
• / Slash
• - Hyphen
• : Colon
• Space

Accessing format information

The Mailcode_Date_FormatInfo class can be used to access information on the available date formats when using the ShowDate command. It is available globally via a factory method:

Setting defaults

The ShowDate command uses Y/m/d as default date format. The format info class can be used to overwrite this:

Once it has been set, whenever the ShowDate command is used without specifying a custom format string, it will use this default format.

Accessing formatting characters programmatically

To make it possible to integrate mailcode in existing documentation, the format info class offers the getFormatCharacters() method to get a list of all characters that can be used.

Displaying a simple text-based list of allowed characters:

Manually validating a date format

Use the validateFormat() method to validate a date format string, and retrieve a validation message manually. The same method is used by the ShowDate command, but can be used separately for specific needs.

Format compatibility

Mailcode mixes well with HTML and XML. Its strict syntax makes it easy to distinguish it from most text formats. with the notable exception of CSS. In HTML, all style tags are ignored.

Safeguarding commands when filtering texts

When texts containing commands need to be filtered, or otherwise parsed in a way that could break the command syntax, the safeguard mechanism allows for easy replacement of all commands with neutral placeholder strings.

Assuming the text to filter, possibly containing commands, is stored in $text:

HINT: Placeholders are case neutral, and thus cannot be broken by changing the text case.

Avoiding delimiter conflicts

By default, the placeholders use 999 as delimiters, for example: 9990000000001999. Each delimiter gets a unique number within the same request, which is zero-padded right, making each placeholder unique in all subject strings.

Having number-based placeholders means that they are impervious to usual text transformations, like changing the case or applying url encoding.

Still, the delimiter string can be adjusted as needed:

This would for example make the delimiters look like __0000000001__.

Placeholder consistency check

When calling makeWhole(), the Safeguard will make sure that all placeholders initially replaced in the target string are still there. If they are not, an exception will be thrown.

Accessing placeholder information

The placeholders used in a string can be easily retrieved. Be sure to call getPlaceholders() after the initial configuration (setting the delimiters, for example).

Applying formatting

By default, when using the safeguard's makeWhole method, all command placeholders are replaced with the normalized syntax of the commands. A number of additional formatting options are available via the safeguard's formatting class. In this case, the formatted string is retrieved via the formatting class instead of the safeguard itself.

Creating a formatting instance, using a safeguard:

Note: Formatting is entirely separate from the safeguard. The safeguard instance retains the original text.

Replacers and Formatters

There are two types of formatters:

• Replacers: These will replace the command placeholders themselves (example: HTML syntax highlighting of commands). Only one replacer may be selected.
• Formatters: These will only modify the text around the placeholder, leaving the placeholder intact. Formatters can be combined at will.

While it is not possible to select several replacers, they can be freely combined with formatters.

The methods to add formatters reflect their type:

HTML Highlighting

The HTML syntax highlighter will add highlighting to all commands in an intelligent way. Commands will not be highlighted if they are used in HTML tag attributes or nested in tags where adding the highlighting markup would break the HTML structure.

This will add the highlighting markup, but the necessary CSS styles must also be available in the document where the Mailcode will be displayed. More on this in the "Loading the required styles" section.

Excluding tags from the highlighting

By default, commands will not be highlighted within the <style> and <script> tags. Additional tags can easily be added to this list to customize it for your needs:

In this example, commands nested in <footer> tags will not be highlighted.

NOTE: The excluded tag check goes up the whole tag nesting chain, which means that the following command would not be highlighted either, since it is contained in a tag that is nested within the <footer> tag:

WARNING: The parser assumes that the HTML is valid. The tag nesting check does not handle nesting errors.

Loading the required styles

For the highlighting to work, the according CSS styles need to be loaded in the target page.

There are two ways to do this:

Including the stylesheet

Ensure that the stylesheet file css/highlight.css of the package is loaded. This requires knowing the exact URL to the package's vendor folder.

Using the Styler utility

The Styler utility class has a number of methods all around the CSS.

Creating/getting the styler instance:

Getting the raw CSS code without the <style> tag, for example, to use in a compiled stylesheet file:

Retrieving the CSS including the <style> tag, for example, to add it inline in a page:

Retrieving the absolute path on disk to the stylesheet file:

Retrieving the <link> tag programmatically, using the URL to access the vendor folder:

Retrieving the URL to the stylesheet file, using the URL to access the vendor folder:

Highlighting variables in the final document

The "MarkVariables" highlighter allows highlighting (not syntax highlighting) all variable type commands, even once they have been processed by the mail preprocessor. This is handy when testing to quickly identify all places in an HTML document where variables are used.

Like the syntax highlighter, this will only highlight variables in valid contexts.

NOTE: This can be combined with any of the other formatters, like the syntax highlighter.

Load styles via style tag

The necessary style tag can be retrieved using the getStyleTag method:

This then only has to be added to the target document.

Integrate styles inline

For HTML mailings, or cases where the styles cannot be easily injected, the inline mode will automatically add the necessary styles to every command instance.

Enable the inline mode like this:

Translation to other syntaxes

The translator class makes it easy to convert documents with mailcode to other syntaxes, like the bundled Apache Velocity converter.

Translating whole strings

Translating single commands

Translate to: Apache Velocity

See the Velocity documentation.

Translate to: Hubspot HubL

See the HubL documentation.

Browser-enabled tools

In the subfolder tools are a few utilities meant to be used in a browser. To use these, run a composer install in the package's folder, and point your browser there.

• Syntax translator: Translate a document with Mailcode commands to a supported syntax.
• Syntax highlighter: Syntax highlighting of a document with Mailcode commands.
• Phone countries extractor: Extracts a country list for the showphone command.