From 2dd32c4a51377b1a110b33babbcf2804638ef337 Mon Sep 17 00:00:00 2001 From: Martin Bens Date: Wed, 28 Jan 2026 16:00:13 +0100 Subject: [PATCH 1/3] docs: document cache:clear:all confirmation behavior --- .../infrastructure/reverse-http-cache.md | 2 +- guides/plugins/apps/app-base-guide.md | 6 +++-- .../plugins/framework/caching/index.md | 12 ++++++++- .../core-reference/commands-reference.md | 26 +++++++++---------- 4 files changed, 29 insertions(+), 17 deletions(-) diff --git a/guides/hosting/infrastructure/reverse-http-cache.md b/guides/hosting/infrastructure/reverse-http-cache.md index b0e082e9f..cea5c47ae 100644 --- a/guides/hosting/infrastructure/reverse-http-cache.md +++ b/guides/hosting/infrastructure/reverse-http-cache.md @@ -214,7 +214,7 @@ So, when a product is invalidated, the object cache and the HTTP cache will also There are a few different cache clearing commands: 1. `bin/console cache:clear` - Clears and warms up the application cache (In versions before 6.7 this command also cleared the HTTP cache) -2. `bin/console cache:clear:all` - Clears everything, including application cache, cache pools and the HTTP cache (Since version 6.6.8) +2. `bin/console cache:clear:all` - Clears everything, including application cache, cache pools, HTTP cache, and other kernel cache directories. Prompts for confirmation in interactive mode; use `--force` to skip (Since version 6.6.8) 3. `bin/console cache:clear:http` - Clears the reverse proxy cache if enabled, if not it clears the `http` cache pool (Since version 6.6.10) 4. `bin/console cache:pool:clear --all` - Clears only the object cache (Useful for when you don't want to clear the http cache, pre version 6.6.10) diff --git a/guides/plugins/apps/app-base-guide.md b/guides/plugins/apps/app-base-guide.md index bbd8ea392..ab6f3c3ca 100644 --- a/guides/plugins/apps/app-base-guide.md +++ b/guides/plugins/apps/app-base-guide.md @@ -85,12 +85,14 @@ If the changes are still not visible, try: bin/console cache:clear:http ``` -or +or for a complete cache reset: ```bash -bin/console cache:clear:all +bin/console cache:clear:all --force ``` +The `--force` flag skips the confirmation prompt that appears in interactive terminals. + By default, your app files will be [validated](app-base-guide#validation) before installation. To skip the validation, you may use the `--no-validate` flag. diff --git a/guides/plugins/plugins/framework/caching/index.md b/guides/plugins/plugins/framework/caching/index.md index 515a42557..b8b34849e 100644 --- a/guides/plugins/plugins/framework/caching/index.md +++ b/guides/plugins/plugins/framework/caching/index.md @@ -409,6 +409,16 @@ sw-force-cache-invalidate: 1 ## Manual cache clear You can also manually clear the caches when you performed some actions that made a cache invalidation necessary, but where it was not triggered automatically. -To clear all caches, you can execute the `cache:clear:all` command, which clears the HTTP-Cache, the object caches as well as any other caches that are registered in the system. + +To clear all caches, you can execute the `cache:clear:all` command, which clears the HTTP-Cache, the object caches as well as removes other kernel cache directories. In interactive terminals, this command prompts for confirmation; use `--force` to skip the prompt. + The `cache:clear` command on the other hand will only clear the object caches, but won't invalidate the HTTP-Cache. On the other hand, the `cache:clear:http` command will clear the complete HTTP-Cache, but won't invalidate the object caches. + +::: details How cache:clear works internally +The Symfony `cache:clear` command uses an atomic directory swap to ensure the application always has a valid cache. It first removes any leftover temporary directories, then creates and warms up the new cache in `var/cache/{env}_new/`. Once ready, it renames the current cache directory to a backup and moves the new one into place. Finally, it removes the backup. + +This approach ensures zero downtime because the application always has a working cache directory. The swap uses filesystem rename operations which are atomic on most systems. On NFS filesystems, directories are deleted instead of renamed due to limitations with atomic operations. + +For more details, see the [Symfony CacheClearCommand source](https://github.com/symfony/symfony/blob/7.4/src/Symfony/Bundle/FrameworkBundle/Command/CacheClearCommand.php). +::: diff --git a/resources/references/core-reference/commands-reference.md b/resources/references/core-reference/commands-reference.md index 6b37dc2aa..6aa56b04f 100644 --- a/resources/references/core-reference/commands-reference.md +++ b/resources/references/core-reference/commands-reference.md @@ -59,19 +59,19 @@ $ bin/console [command] [parameters] ### Cache -| Command | Description | -|:-----------------------------|:------------------------------------------------------------------------------------------------| -| `cache:clear` | Clears the cache | -| `cache:clear:all` | Clear all caches/pools, invalidates expired tags, removes old system and twig cache directories | -| `cache:clear:delayed` | Invalidates the delayed cache keys/tags | -| `cache:clear:http` | Clear only the HTTP cache | -| `cache:pool:clear` | Clears cache pools | -| `cache:pool:delete` | Deletes an item from a cache pool | -| `cache:pool:invalidate-tags` | Invalidate cache tags for all or a specific pool | -| `cache:pool:list` | Lists available cache pools | -| `cache:pool:prune` | Prunes cache pools | -| `cache:warmup` | Warms up an empty cache | -| `cache:watch:delayed` | Watches the delayed cache keys/tags | +| Command | Description | +|:-----------------------------|:---------------------------------------------------------------------------------------------------------------------------------| +| `cache:clear` | Clears the cache | +| `cache:clear:all` | Clears all caches/pools, invalidates expired tags, removes old kernel cache directories. Requires confirmation or `--force` flag | +| `cache:clear:delayed` | Invalidates the delayed cache keys/tags | +| `cache:clear:http` | Clear only the HTTP cache | +| `cache:pool:clear` | Clears cache pools | +| `cache:pool:delete` | Deletes an item from a cache pool | +| `cache:pool:invalidate-tags` | Invalidate cache tags for all or a specific pool | +| `cache:pool:list` | Lists available cache pools | +| `cache:pool:prune` | Prunes cache pools | +| `cache:warmup` | Warms up an empty cache | +| `cache:watch:delayed` | Watches the delayed cache keys/tags | ### Cart From c79067d1ed812ca98ef3e17492ac2f3308743d7b Mon Sep 17 00:00:00 2001 From: Martin Bens Date: Wed, 28 Jan 2026 19:58:01 +0100 Subject: [PATCH 2/3] docs: document cache:clear:all confirmation and hash implications --- .../installation-updates/deployments/build-w-o-db.md | 12 ++++++++++++ guides/plugins/plugins/framework/caching/index.md | 4 ++++ 2 files changed, 16 insertions(+) diff --git a/guides/hosting/installation-updates/deployments/build-w-o-db.md b/guides/hosting/installation-updates/deployments/build-w-o-db.md index 81ef755fc..2e0923532 100644 --- a/guides/hosting/installation-updates/deployments/build-w-o-db.md +++ b/guides/hosting/installation-updates/deployments/build-w-o-db.md @@ -1376,3 +1376,15 @@ index.json ### Partially compiling the Storefront You can also build just the Javascript bundle using `CI=1 SHOPWARE_SKIP_THEME_COMPILE=true PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true bin/build-storefront.sh` (without the need for the above loader) in your CI. After that, run `bin/console theme:dump` on your production system when the database is available. This will happen automatically if theme variables are changed via the admin panel. + +## Cache directory and hash implications + +When using `bin/ci` or `ComposerPluginLoader`, the cache directory name includes a hash computed from active plugins. Since `ComposerPluginLoader` marks all Composer-installed plugins as active, while `DbalKernelPluginLoader` (used by web requests) respects the database `active` column, the cache hashes can differ. + +This means: + +- Cache warmed with `bin/ci` uses a hash based on all Composer-installed plugins being active +- Production web requests use a hash based on actual database plugin state +- If any plugin is deactivated in the database, web requests create a new cache directory + +To ensure cache is properly cleared across all configurations, use `cache:clear:all` instead of `cache:clear` in deployment scripts. In interactive terminals, this command prompts for confirmation; use `--force` to skip the prompt in CI/CD pipelines. diff --git a/guides/plugins/plugins/framework/caching/index.md b/guides/plugins/plugins/framework/caching/index.md index b8b34849e..9addf4243 100644 --- a/guides/plugins/plugins/framework/caching/index.md +++ b/guides/plugins/plugins/framework/caching/index.md @@ -415,6 +415,10 @@ To clear all caches, you can execute the `cache:clear:all` command, which clears The `cache:clear` command on the other hand will only clear the object caches, but won't invalidate the HTTP-Cache. On the other hand, the `cache:clear:http` command will clear the complete HTTP-Cache, but won't invalidate the object caches. +::: warning +`cache:clear` only clears the cache directory matching the current kernel's configuration. If you run `bin/console cache:clear` but web requests still use stale cache, the CLI and web server may be using different cache directories. This can happen when plugins are in different states (e.g., installed via Composer but not yet activated in the database). Use `cache:clear:all` to clear all cache variants. +::: + ::: details How cache:clear works internally The Symfony `cache:clear` command uses an atomic directory swap to ensure the application always has a valid cache. It first removes any leftover temporary directories, then creates and warms up the new cache in `var/cache/{env}_new/`. Once ready, it renames the current cache directory to a backup and moves the new one into place. Finally, it removes the backup. From 88cc7d0d12a2b87ecfb65a3f84abf8631b492a2f Mon Sep 17 00:00:00 2001 From: Martin Bens Date: Wed, 28 Jan 2026 20:26:10 +0100 Subject: [PATCH 3/3] chore: add CacheClearCommand and NFS to spellcheck wordlist --- .wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 53ba97434..a85bd4759 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -129,6 +129,7 @@ CSP CSPs CSRF CSV +CacheClearCommand CacheInvalidator CacheInvalidatorS CachedProductListingRouteTest @@ -585,6 +586,7 @@ MyExtension MyPlugin MyTestClass MyTestInterface +NFS NPM NUR NVDA