The replaceInsertTags hook is triggered when an unknown insert tag is found. It passes the insert tag as argument and expects the replacement value or false as return value.

See also the dedicated framework article about Insert Tags.


  1. string $insertTag

    The unknown insert tag.

  2. bool $useCache

    Indicates if we are supposed to cache.

  3. string $cachedValue

    The cached replacement for this insert tag (if there is any).

  4. array $flags

    An array of flags used with this insert tag.

  5. array $tags

    Contains the result of spliting the page’s content in order to replace the insert tags.

  6. array $cache

    The cached replacements of insert tags found on the page so far.

  7. int $_rit

    Counter used while iterating over the parts in $tags.

  8. int $_cnt

    Number of elements in $tags.

Return Values

Return a string if your function is taking care of this insert tag. The hook loop will be stopped and your output is used as a replacement value.

If your function is not responsible for this insert tag, you must return false to continue to the next hook callback.


// src/EventListener/ReplaceInsertTagsListener.php
namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;

class ReplaceInsertTagsListener
    public function __invoke(
        string $insertTag,
        bool $useCache,
        string $cachedValue,
        array $flags,
        array $tags,
        array $cache,
        int $_rit,
        int $_cnt
        if ('mytag' === $insertTag) {
            return 'mytag replacement';

        return false;