module Cacheable Placeholders - Dynamic replacements for cached content

[MoritzLost 508]

Cacheable Placeholders

This module allows you to have pieces of dynamic content inside cached output. This aims to solve the common problem of having a mostly cacheable site, but with pieces of dynamic output here and there.  Consider this simple example, where you want to output a custom greeting to the current user:

<h1>Good morning, <?= ucfirst($user->name) ?></h1>

This snippet means you can't use the template cache (at least for logged-in users), because each user has a different name. Even if 99% of your output is static, you can only cache the pieces that you know won't include this personal greeting. A more common example would be CSRF tokens for HTML forms - those need to be unique by definition, so you can't cache the form wholesale.

This module solves this problem by introducing cacheable placeholders - small placeholder tokens that get replaced during every request. The replacement is done inside a Page::render hook so it runs during every request, even if the response is served from the template cache. So you can use something like this:

<h1>Good morning, {{{greeting}}}</h1>

Replacement tokens are defined with a callback function that produces the appropriate output and added to the module through a simple hook:

// site/ready.php
wire()->addHookAfter('CachePlaceholders::getTokens', function (HookEvent $e) {
    $tokens = $e->return;
    $tokens['greeting'] = [
        'callback' => function (array $tokenData) {
            return ucfirst(wire('user')->name);
        }
    ];
    $e->return = $tokens;
});

Tokens can also include parameters that are parsed and passed to the callback function. There are more fully annotated examples and step-by-step instructions in the README on Github!

Features

• A simple and fast token parser that calls the appropriate callback and runs automatically.
• Tokens may include multiple named or positional parameters, as well as multi-value parameters.
• A manual mode that allows you to replace tokens in custom pieces of cached content (useful if you're using the $cache API).
• Some built-in tokens for common use-cases: CSRF-Tokens, replacing values from superglobals and producing random hexadecimal strings.
• The token format is completely customizable, all delimiters can be changed to avoid collisions with existing tag parsers or template languages.

Links

• Github Repository & documentation
• Module directory (pending approval)

If you are interested in learning more, the README is very extensive, with more usage examples, code samples and usage instructions!

[d'Hinnisdaël 184]

This looks great, thanks for open-sourcing! Am I right in assuming that the callbacks will only get invoked if the matching placeholder is found in the server response?