lameco / craft-blitz
Laméco defaults for Blitz: forced cache settings and per-site query string exclusions
Package info
github.com/Lameco-Development/craft-blitz
Type:craft-plugin
pkg:composer/lameco/craft-blitz
Requires
- php: ^8.2
- craftcms/cms: ^5.0
- putyourlightson/craft-blitz: ^5.0
Requires (Dev)
- craftcms/ecs: dev-main
- craftcms/phpstan: dev-main
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- 6.1.0
- 6.0.1
- 6.0.0
- 5.0.1
- 5.0.0
- 4.0.0
- 1.1.2
- 1.0.2
- 1.0.1
- 1.0.0
- 0.2.2
- 0.2.0
- 0.1.4
- 0.1.3
- 0.1.2
- 0.1.1
- 0.1.0
- dev-development
- dev-docs/local-generator-only
- dev-fix/translation-refresh-on-failed-sync
- dev-feature/translation-cache-tags
- dev-docs/translation-refresh-wording
- dev-fix/refresh-on-translation-sync
- dev-feature/craft5-release-please
- dev-fix/cache-cached-includes
- dev-fix/query-param-presence
This package is auto-updated.
Last update: 2026-11-12 12:57:42 UTC
README
Laméco defaults for Blitz: it forces one set of Blitz settings on every site and lets each site name the query string parameters that must bypass the cache.
Requirements
- PHP 8.2 or higher
- Craft CMS 5
- Blitz 5, installed and enabled
Installation
composer require lameco/craft-blitz:^6.0 php craft plugin/install _craft-blitz
The constraint matters: Packagist also carries the tags 4.0.0, 5.0.0 and 5.0.1 from an older implementation (2024).
What it forces
The plugin overrides these Blitz settings at runtime, whatever the Blitz CP settings or config/blitz.php say:
| Blitz setting | Value |
|---|---|
| Caching enabled | BLITZ_ENABLED (default off) |
| Debug | BLITZ_DEBUG (default off) |
| Included URI patterns | every URI, every site |
| Generator | LocalGenerator when BLITZ_GENERATOR=LOCAL, otherwise HttpGenerator, with concurrency 1 |
| Storage | compressed cached values |
| Refresh mode | expire the cache |
| Query string caching | cache URLs with query strings as the same page |
| Included / excluded query string params | none |
BLITZ_GENERATOR=LOCAL is for local development only, where Blitz's HTTP generator can't reach Valet's .test domains. Servers use HTTP: the local generator can't rebuild craft.blitz.includeCached() fragments, so an expired header or footer stays up.
Only pages that resolve to an entry are cached, plus the fragments of craft.blitz.includeCached().
Translations
With Enupal Translate installed, a changed site translation expires only the cached pages and craft.blitz.includeCached() fragments that show it, as Blitz recommends for content it can't track itself (craft-blitz#649):
- While Blitz caches a page or fragment, the plugin tags it with every site translation (
|t,Craft::t('site', …)) it renders. - Enupal writes each save, import or provider translation to the translation file and queues its "Syncing translations with DB" job. Just before that job runs, the plugin compares Enupal's database copy with the files, and afterwards expires the pages tagged with a changed message. A change in
translations/nl/also covers the regions that fall back to it, such asnl-NL. - If Enupal's database copy is behind the files, for example when translations were changed in git, the next sync treats those messages as changed too.
This needs a queue runner, and only happens while Blitz caching is enabled (BLITZ_ENABLED). As with any expired page, the first visit still gets the old text and queues the regeneration; the visits after that get the new text. A site that configures its own message source for the site category isn't tagged; there, a sync expires the whole cache. Edits to plugin translations through Enupal are not tracked.
Pages cached before 6.1.0 carry no translation tags, so clear the Blitz cache once after updating.
Query string exclusions
Because every URL with a query string is cached as the same page, a parameter that changes the output has to be listed, or its render ends up in the cache under the plain URL for every visitor. A listed parameter makes the request bypass the cache whenever it is present, whatever its value (?q=0, ?q= and ?q included). Blitz neither serves such a request from the cache nor stores it.
- Global query string params: a comma-separated list that applies to every page, for example
q,page. - Per section and entry type: rows of a section/entry type and its comma-separated parameters.
Write array parameters with or without brackets: filters[] matches ?filters[]=1 and ?filters[0]=1. Both settings can also be set in config/_craft-blitz.php, which then overrides the CP.
Upgrading
- From 1.x: require
^6.0, runphp craft up, then clear the Blitz cache, since pages cached under the old rules stay in the cache otherwise. - From 5.0.x: the same. The migration converts the 5.0.x rows, which stored a section ID, into one row per entry type of that section, and logs a warning for rows whose section no longer exists. The listed parameters now bypass the cache instead of being cached as separate pages. Run the migration in the environment where project config is edited and commit the YAML; other environments pick it up when project config is applied.