rah / rah_vinyl
Vinyl Cache based full-page cache integration for Textpattern CMS
Requires
- php: >=8.1
- ext-curl: *
- textpattern/installer: *
- textpattern/lock: >=4.7.0
Requires (Dev)
- brain/monkey: ^2.7
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^13.3
- rah/mtxpc: ^0.9.0
- squizlabs/php_codesniffer: 3.*
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A plugin for Textpattern CMS that provides full-page caching support using Vinyl Cache. The plugin allows running Textpattern CMS behind Vinyl Cache proxy, where the plugin will handle flushing the cache stored in Vinyl when content is updated in Textpattern CMS. Pages that have been cached, are stored directly from Vinyl Cache’s proxy, without the request hitting Textpattern CMS, or requiring processing from PHP.
Install
Using Composer:
$ composer require rah/rah_vinyl
Or download an installer package.
Requirements
- Textpattern >= 4.7.0.
- PHP >= 8.1.0.
- Vinyl Cache or Varnish server.
Configuration
Texpattern
Connected Vinyl Cache server can be configured through Textpattern’s textpattern/config.php file:
define('RAH_VINYL_BASEURL', 'http://vinyl-cache.tld');
The RAH_VINYL_BASEURL is expected to contain a full URL address from where the Vinyl Cache backend can be reached.
Vinyl Cache
Vinyl Cache, or Varnish, server is highly configurable, and how it’s cache functions is customizable within it’s configuration. An example VLC configuration file, example/default.vcl, is provided as a basis for configuration. To use the example configuration, you would at least need to change the default backend and purge hostnames. The default backend hostname is where the Textpattern CMS installation can be found from, and Vinyl Cache proxy routes the request there, caching the backend response for reuse. The purge hostnames define the addresses that can control the Vinyl Cache server and purge cached contents from it. In general, access control in Vinyl Cache, and Varnish, is done with hostname whitelists, private or otherwise, or IP addresses.
The Textpattern plugin will send custom HTTP request method PURGE and PURGEALL to the Vinyl Cache server, which are targeted in the example configuration for flushing the cache. The PURGEALL method is expected to flush the whole cache, and X-Pool header can be used with PURGE method to clear singular items based on tags and partial patterns.
The plugin will send PURGEALL request to Vinyl Cache, if any content is created, updated or deleted via Textpattern CMS’s admin panel.
Tag and attributes
The plugin, rah_vinyl, introduces a new self-closing tag to Textpattern’s arsenal. The tag can be used to instruct Vinyl Cache to ignore pages where the tag has been rendered, add X-Pool tag identifiers to pages or flush the cache on demand.
<rah::vinyl />
The tag is a container and attributes for it follow.
ignore
If used, tells Vinyl Cache to ignore the page, skip cache and pass the request to the Textpattern backend. When the tag is used with ignore attribute, it will add X-Pool: ignore header to the page’s response, which can then be used in Vinyl Cache’s VLC configuration to skip caching, passing the request directly to Textpattern’s backend.
Default: undefined Example: ignore
tags
Specifies tags that are added to the current page. Sends the given comma-separated list of tags as the X-Pool header with the page’s response, which can then be used in Vinyl Cache’s VLC configuration to associate pool tags with the page, allowing cache purges to target the page based on a tag.
Default: undefined Example: tags="profile"
purge
Sends purge request to the Vinyl Cache backend when specified. The purge request is executed right away when the tag is rendered. If tags attribute is given, sends PURGE method request with X-Pool header containing the given tags. If tags attribute is not given, sends PURGEALL request to Vinyl Cache. Keep in mind that for the purging to function, this tag should be used on a page that is not cache. Pages can be prevent to be cache via the ignore attribute, or including the tag on a form’s POST request’s response page.
Default: undefined Example: purge
Examples
Do not cache page in Vinyl Cache
The following would add X-Pool: ignore header to the page’s response:
<rah::vinyl ignore />
Add specified tags to to the page
The following would add tag1, tag2, tag3 and tag4 X-Pool tags to the page’s response:
<rah::vinyl tags="tag1, tag2" />
<rah::vinyl tags="tag2, tag3" />
Manually purge all content
The following would send PURGEALL request to Vinyl Cache:
<rah::vinyl purge />
Manually purge specified tags
The following would send PURGE request to Vinyl Cache with X-Pool header containing the specified tags:
<rah::vinyl purge tags="tag1, tag2" />
Changelog
Version 0.2.0 – 2026/11/16
- Tag’s
ignoreattribute removes and overwrites any other tags declared earlier on the same page. - All Textpattern CMS pages now send `X-Pool` header with at least `Textpattern` tag in it, even in cases where no tags were declared on the page.
Version 0.1.0 – 2026/11/15
- Initial release.