module Cacheable Placeholders - Dynamic replacements for cached content

[MoritzLost]

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

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

[d'Hinnisdaël]

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?

[MoritzLost]

17 hours ago, d'Hinnisdaël said:

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?

Yes! The module uses preg_replace_callback to look for cache tokens and calls the corresponding callback for each occurance. BTW this also means that if you use the same token multiple times, the callback will be called that many times as well (for most tokens this will be the desired / expected behaviour).

[MoritzLost]

v1.0.1

• Bugfix: Fix warnings in PHP 8.2 (contributed by esszett in #1)