PHPackages alpshq/statamic-cache-evader - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Caching](/categories/caching) 4. / 5. alpshq/statamic-cache-evader ActiveStatamic-addon[Caching](/categories/caching) alpshq/statamic-cache-evader ============================ A statamic Addon to help you evade the static cache and support forms on cached pages. v1.4.1(3y ago)4135[2 issues](https://github.com/alpshq/statamic-cache-evader/issues)MITPHP Since Feb 18Pushed 2y ago1 watchersCompare [ Source](https://github.com/alpshq/statamic-cache-evader)[ Packagist](https://packagist.org/packages/alpshq/statamic-cache-evader)[ RSS](/packages/alpshq-statamic-cache-evader/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (9)Dependencies (1)Versions (10)Used By (0) Cache Evader ============ [](#cache-evader) > Cache evasion for Statamic 3 This Addon provides various simple ways to serve **uncached content** on **cached pages** and makes it possible to use Statamic forms on cached pages. What you can do --------------- [](#what-you-can-do) - [Serve whole uncached pages based on an HTTP GET parameter](https://github.com/alpshq/statamic-cache-evader#usage-cache-evading-based-on-http-get-parameter) - [Use Statamic forms on cached pages](https://github.com/alpshq/statamic-cache-evader#usage-forms) - **NEW**: [Inject uncached partials as part of cached pages](https://github.com/alpshq/statamic-cache-evader#usage-inject-uncached-partials-as-part-of-cached-pages) Support ------- [](#support) If you like the Addon consider [following me on Twitter](https://twitter.com/jakub_jo). If you've feature requests, feel free to start a discussion by opening a GitHub issue. If you've any further questions or want to discuss an opportunity with me, drop me a line at . Installation ------------ [](#installation) You can install the addon using composer: ``` composer require alpshq/statamic-cache-evader ``` Alternatively you can install the addon by navigating to [Statamic's marketplace](https://statamic.com/addons/alps/cache-evader) within your Control Panel and searching there for `Cache Evader`. Usage: Cache evading based on HTTP GET parameter ------------------------------------------------ [](#usage-cache-evading-based-on-http-get-parameter) Essentially any URL to which you add the GET parameter `_nc` with *any* value will evade the cache. ### Modifier [](#modifier) To add the corresponding HTTP parameter name to any URL you can use the built-in modifier [evade\_cache](src/Modifiers/EvadeCache.php): ``` Link to current (uncached) URL ``` #### How does the cache evading work? [](#how-does-the-cache-evading-work) - The Addon will replace Statamic's default Cache middleware with the Addon's [StaticCache](src/Http/Middleware/StaticCache.php) middleware. - The replaced middleware will check if a cache evading parameter is part of the request. If a parameter is found, the cache is evaded. If not, Statamic default behavior applies. Usage: Forms ------------ [](#usage-forms) To make your forms work in cached environments make sure to add the [{{ cache\_evader\_scripts }}](src/Tags/CacheEvaderScripts.php) tag right before the closing `` tag. Add it either on every page which contains forms or add it to your layout globally: ``` ... {{ template_content }} ... {{ cache_evader_scripts }} ``` The tag will load a script which will add a hidden input field with the name `_xsrf_token` and the value of the XSRF cookie to all your forms. The [SpoofXsrfHeader](src/Http/Middleware/SpoofXsrfHeader.php) middleware will make sure the added field gets validated by the default Laravel CSRF protection middleware. In order to get meaningful error and success messages for your users you need to make sure the forms redirect to an **uncached** page. Within your forms add `_redirect` and `_error_redirect` links containing the cache evading HTTP parameter mentioned in the beginning. The simplest way to achieve this is by using the `evade_cache` modifier: ``` {{ form:create handle="contact-form" }} {{ /form:create }} ``` After a submission, the above form will redirect you to the uncached version of the current page displaying all dynamic content, such as error and success messages. That's it. Your forms will work as if there was no cache at all. ### How does it work in detail? [](#how-does-it-work-in-detail) - The [script](resources/js/app.js) which you pull in with the [{{ cache\_evader\_scripts }}](src/Tags/CacheEvaderScripts.php) tags will loop through all your forms and add the current `XSRF-TOKEN` cookie value to the form by appending a hidden input field with the name `_xsrf_token`. - If no such Cookie exists (This is especially the case when you're using the `full` cache strategy and the current user was served by the static file cache): - The script will make a lightweight fetch request to the `cache-evader.ping` route (`/cache-evader/ping`). - Laravel will respond with the `XSRF-TOKEN` cookie attached. - All following visits and requests have access to the `XSRF-TOKEN` cookie and no further fetch request will be made. - The [`SpoofXsrfHeader`](src/Http/Middleware/SpoofXsrfHeader.php) middleware will populate the request's `x-xsrf-token` header with the value of the `_xsrf_token` field. It pretty much reproduces current SPA behavior, which is [mentioned in the Laravel documentation](https://laravel.com/docs/9.x/csrf#csrf-x-xsrf-token). Inspiration came from Laravel's [form method spoofing](https://laravel.com/docs/9.x/routing#form-method-spoofing) Usage: Inject uncached partials as part of cached pages ------------------------------------------------------- [](#usage-inject-uncached-partials-as-part-of-cached-pages) Wouldn't it be fine if you could utilize Statamic's full caching strategy while displaying **dynamic content** on your pages? Look no further -- you've found the solution. With the help of **uncached** partials inside your **cached** pages you can get the best out of both worlds. ### Setting it up [](#setting-it-up) To enable injecting of custom partials make sure to add the [{{ cache\_evader\_scripts }}](src/Tags/CacheEvaderScripts.php) tag right before the closing `` tag. Add it either on every page on which you'll use the `{{ cache_evader_partial }}` tag or add it to your layout globally: ``` ... {{ template_content }} ... {{ cache_evader_scripts }} ``` The tag will load a script which will fetch the contents of your uncached partials by sending an immediate `fetch` request for each partial. The fetch request will evade the cache and load any dynamic content you specifiy in your partials. ### Basic Usage [](#basic-usage) First things first: Create a simple partial which contains dynamic content: `partials/user.antlers.html`. ``` {{ if logged_in }} Welcome {{ current_user:email }} {{ else }} Please login. {{ /if }} ``` Now simply include the partial in your template using the `{{ cache_evader_partial }}` tag: ``` {{ cache_evader_partial:user }} ``` **That's it.** Your **fully cached page** will now **always** display your user's email! ### Parameters [](#parameters) You can add any number of parameters to your partial. You can access the parameters as regular variables in your partial. > **Important:** > Keep in mind, parameters are publicly visible -- don't share secrets using parameters! ``` {{ if logged_in }} Welcome {{ current_user:email }} {{ else }} Please login. {{ /if }} ``` ``` {{ cache_evader_partial:user login_url="/login" }} ``` ### Displaying a loading message [](#displaying-a-loading-message) You can display a loading message or an indicator. Simply wrap your loading indicator in the tag pair: ``` {{ cache_evader_partial src="user" login_url="/login" }} Loading login state ... {{ /cache_evader_partial }} ``` ### Placeholder element [](#placeholder-element) When you include a partial using the `{{ cache_evader_partial }}` tag, a placeholder `div` will be rendered instead of the partial. The placeholder is eventually swaped out with the content of your partial. You can change the placeholder by adding a `wrap` parameter: `{{ cache_evader_partial src="..." wrap="span" }}`. ### Wrapping of your partial's content [](#wrapping-of-your-partials-content) Your partial's content will be wrapped in a `div` element. You can avoid this behaviour by rendering a single root element in your partial. **This will be wrapped in a `div`:** ``` Welcome {{ current_user:email }}! Not {{ current_user:email }}? ``` **This will NOT be wrapped in a `div`:** ``` Welcome {{ current_user:email }}! Not {{ current_user:email }}? ``` ### Script tags [](#script-tags) Yes! You can include script tags in your partials. They'll be executed. ``` {{ if logged_in }} Welcome {{ current_user:email }} {{ else }} Please login. {{ /if }} ``` ### JavaScript Hooks [](#javascript-hooks) #### Before a fetch request is sent [](#before-a-fetch-request-is-sent) Before each fetch request is sent to your server the `cacheEvaderBeforeInject` event is triggered on the placeholder element. You can cancel the fetch request by invoking `preventDefault()` on the event. ``` window.addEventListener('cacheEvaderBeforeInject', ev => { ev.preventDefault(); // No fetch request is sent. // ev.target -- The placeholder element // ev.detail -- See below which properties are available. }); ``` The event will have a `detail` property which contains the url to which the request is sent and also all the parameters you've supplied to the partial. NameTypePurposeurl`string`The URL which will render the partial's contentsparams`object`An object which contains all the parameters you've supplied to the partialparams.view`string`The path to the partialparams.signature`string`Laravel's URL signature#### After the content was injected [](#after-the-content-was-injected) After the dynamic content of your partial was fetched & injected into the DOM the `cacheEvaderAfterInject` event is triggered on the injected element. ``` window.addEventListener('cacheEvaderAfterInject', ev => { // ev.target -- See below what the target will be. // ev.detail -- See below which properties are available. }); ``` The value of the event `target` will be the wrapping element of your partial. If your partial does have a single root element, the value of `target` will be your root element. Otherwise it'll be a wrapping `div`. The event will have a `detail` property which contains the url to which the request was sent to, all the parameters you've supplied to the partial and the server's response. NameTypePurposeresponse`Response`The response objecturl`string`The URL which will render the partial's contentsparams`object`An object which contains all the parameters you've supplied to the partialparams.view`string`The path to the partialparams.signature`string`Laravel's URL signature### How do dynamic partials work in detail? [](#how-do-dynamic-partials-work-in-detail) - When using the `{{ cache_evader_partial }}` tag, a placeholder will be rendered with no actual content. - The JavaScript you add to the browser using the `{{ cache_evader_scripts }}` tag will iterate over each placeholder and will send a fetch request to the server - Your server renders the partial and sends it to the browser - The placeholder will be swaped with the actual content Configuration ------------- [](#configuration) You can publish the configuration file to modify the default parameter name (`_nc`), and the default value (`!`): ``` php artisan vendor:publish --tag=cache-evader-config ``` You'll find the published [configuration file](config/cache-evader.php) in `config/statamic/cache-evader.php` -- review it for explanation about the various options. Security -------- [](#security) If you encounter any security related issues, please email directly instead of opening an issue. All security related issues will be promptly addressed. License ------- [](#license) MIT -- see the [license file](LICENSE.md). ### Health Score 24 — LowBetter than 32% of packages Maintenance10 Infrequent updates — may be unmaintained Popularity14 Limited adoption so far Community7 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~10 days Total 9 Last Release 1458d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f68abf0a6ec7b0fcbcd0d4781b38396e4139f109ec1e0d605b82013acf38ac4b?d=identicon)[jakubjo](/maintainers/jakubjo) --- Top Contributors [![jakubjo](https://avatars.githubusercontent.com/u/2873852?v=4)](https://github.com/jakubjo "jakubjo (45 commits)") --- Tags statamic-addon ### Embed Badge ![Health badge](/badges/alpshq-statamic-cache-evader/health.svg) ``` [![Health](https://phpackages.com/badges/alpshq-statamic-cache-evader/health.svg)](https://phpackages.com/packages/alpshq-statamic-cache-evader) ``` ### Alternatives [predis/predis A flexible and feature-complete Redis/Valkey client for PHP. 7.8k305.7M2.4k](/packages/predis-predis)[snc/redis-bundle A Redis bundle for Symfony 1.0k39.4M67](/packages/snc-redis-bundle)[react/cache Async, Promise-based cache interface for ReactPHP 444112.4M40](/packages/react-cache)[illuminate/cache The Illuminate Cache package. 12835.6M1.4k](/packages/illuminate-cache)[colinmollenhour/php-redis-session-abstract A Redis-based session handler with optimistic locking 6325.6M14](/packages/colinmollenhour-php-redis-session-abstract)[amphp/redis Efficient asynchronous communication with Redis servers, enabling scalable and responsive data storage and retrieval. 165634.7k44](/packages/amphp-redis) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)