Parsing MODX Tags

Use this when you need snippet, chunk, or lexicon tags parsed outside the normal page render: generating email bodies, or returning fully processed content from an API.

modX::getChunk already runs the parser over a chunk. What it leaves behind are uncacheable tags — [[!Wayfinder]], [[!getResources?…]] — because modChunk::process() passes the parser’s isProcessingUncacheable() flag, and that flag is false outside a render.

modParser::processElementTags() is the way to finish the job.

From a chunk¶

getChunk() has already processed the cacheable tags, so one pass is enough:

$content = $modx->getChunk('MyChunkName', ['foo' => 'bar']);

$parser = $modx->getParser();
$maxIterations = (integer) $modx->getOption('parser_max_iterations', null, 10);

// Process uncached tags, stripping anything that could not be processed
$parser->processElementTags('', $content, true, true, '[[', ']]', [], $maxIterations);

return $content;

From raw content¶

modElement::getContent() returns the source as stored, with every tag intact. Parse it in two passes: the first handles cacheable tags, the second uncacheable ones.

$chunk = $modx->getObject('modChunk', 'MyChunkName');
$content = $chunk->getContent();

$parser = $modx->getParser();
$maxIterations = (integer) $modx->getOption('parser_max_iterations', null, 10);

$parser->processElementTags('', $content, false, false, '[[', ']]', [], $maxIterations);
$parser->processElementTags('', $content, true, true, '[[', ']]', [], $maxIterations);

return $content;

[!WARNING] Each call to processElementTags() fires the OnParseDocument plugin event. The two-pass recipe above therefore triggers it twice — plugins on that event run their logic twice and can rewrite the content through the passed reference.

Method reference¶

$processed = $parser->processElementTags(
    $parentTag,
    &$content,
    $processUncacheable = false,
    $removeUnprocessed = false,
    $prefix = '[[',
    $suffix = ']]',
    $tokens = [],
    $depth = 0
);

The return value is the number of tags processed.

Parser depth¶

$depth counts additional passes, not nesting levels. The counter drops by one on entry and another pass runs only while it is above zero, so 10 yields at most ten passes over the content.

The value comes from parser_max_iterations, which is not a system setting — it does not appear in the manager. modX::getOption() falls back to $modx->config, so set it in core/config/config.inc.php:

$config_options = ['parser_max_iterations' => 20];

The default is 10.

Why two passes¶

parser_recurse_uncacheable (a real system setting, enabled by default) stops the parser from writing uncacheable output into cacheable content. With it disabled, uncacheable element output can end up cached inside the surrounding cacheable content — which is why the uncacheable pass comes last.

See also¶

• modX::getChunk
• modChunk::getContent()
• modChunk::process()
• Tag syntax