Download the PHP package daun/statamic-cache-directives without Composer

Statamic Cache Directives

Parse conditional HTML comment directives after Statamic has rendered a page, so cached pages can still include small dynamic fragments.

This package is a lightweight alternative to Statamic's nocache tag. It is useful for tiny auth-, role-, or request-dependent islands where you only need to keep or remove existing markup without the overhead of the nocache data/session pipeline.

It is implemented as a static caching replacer for Statamic's half-measure static cache.

Installation

Install the package via composer:

Registration

Enable the replacer in config/statamic/static_caching.php.

Usage

Wrap markup in conditional comments. Matching blocks are kept when their expression evaluates to true; otherwise they are removed from the response.

The second format follows the downlevel-hidden syntax for conditional comments.

Syntax

Expressions use Symfony Expression Language syntax.

If

Unless

Not

Use either ! or not.

And

Use and or &&.

Or

Use or or ||.

Echo

Use echo to print a variable value. Echo directives can be standalone or block-style. Output is escaped for html contexts.

Raw

Use raw to print a variable value without escaping. Use this only for values you fully control as printing untrusted data with raw is an XSS vector.

Combined expressions

Use parentheses to group subexpressions or override precedence.

Nested data and object methods

Use [] for array keys and . for object properties or methods.

Unknown variable names throw an InvalidArgumentException, so typos fail loudly.

Built-in variables

These variables are available by default and can be used in expressions:

• logged_in: Current Statamic user is authenticated.
• logged_out: Current Statamic user is not authenticated.
• cp_access: Current Statamic user has control panel access.
• super: Current Statamic user is a super admin.

Authentication uses Statamic's configured control-panel guard: config('statamic.users.guards.cp').

Real-world examples

Seed frontend auth state

Swap account navigation without nocache

Show edit links to super admins

Hide conversion prompts from signed-in users

Load control-panel JavaScript

Custom variables

Add custom variables during application boot using variable() or variables(). Values can be scalar values, arrays, objects or closures. Closures are evaluated lazily when the variable is first encountered.

Use closures for request-dependent values such as auth, session, request data, or GeoIP lookups. In long-lived worker runtimes such as FrankenPHP, Swoole, RoadRunner, or Laravel Octane, service providers can boot once per worker instead of once per request. Passing a direct value would capture the value at boot; passing a closure resolves it for the current request.

For bulk registration, use variables().

Then use those variables in comments:

Disabling a response

If a response contains this marker anywhere, directive parsing is skipped for the whole response. Use it as a kill switch on routes that must never be processed (for example email or preview endpoints).

Ignoring a range

Wrap a section in ignore markers to leave it verbatim while the rest of the response is still parsed. Directives inside the range are not processed, and the wrapper comments are removed from the output. This is useful for fragments that legitimately contain conditional comments (for example Outlook <!--[if mso]> markup) or documentation showing directive syntax.

[!WARNING] Both markers control directive processing, so they must never originate from untrusted, user-controlled content. See Security below.

Security

This replacer scans the entire cached HTML response for directive comments. Cached pages frequently contain user-generated content (comments, reviews, usernames, profile fields, reflected search queries, form echoes). If any of that content can contain the strings below, it can subvert directive processing:

• <!--[cache-directives-disable]--> disables all directive processing for the page. An attacker who injects it can prevent auth-gated blocks such as <!--[if super]-->...<!--[endif]--> from being stripped, exposing that markup to every visitor.
• <!--[cache-directives-ignore]--> … <!--[cache-directives-endignore]--> leaves an arbitrary range unprocessed, which can likewise expose auth-gated markup wrapped inside it.
• <!--[if ...]--> / <!--[echo ...]--> markers let injected content pair with, hide, or reveal surrounding directive blocks.

To stay safe, strip or neutralize directive comments from user-controlled content before it is rendered into a cacheable page. For example, remove <!--[ sequences from user input, or escape them:

Failure handling:

• A directive that fails to evaluate (for example an unknown variable) is removed (fails closed) rather than throwing, so a single malformed or injected directive cannot break the whole page. The error is reported to your logger.
• When app.debug is enabled (local/dev), the failure is rethrown instead, so template typos surface loudly during development.

License

MIT