docs: document cache:clear:all and cache hash behavior (#2088)

* docs: document cache:clear:all confirmation behavior

* docs: document cache:clear:all confirmation and hash implications

* chore: add CacheClearCommand and NFS to spellcheck wordlist

* docs(cache): remove cache:clear:all confirmation prompt references

Removes documentation about the interactive confirmation prompt and --force flag for the cache:clear:all command across all guide pages.

* Update resources/references/core-reference/commands-reference.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update guides/plugins/plugins/framework/caching/index.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore/grammar

* chore/grammar

* chore/streamline-command-descriptions

* fix/other-prs-spellcheck

* fix/other-usage

---------

Co-authored-by: Micha Hobert <m.hobert@shopware.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.wordlist.txt

@@ -129,6 +129,7 @@ CSP
 CSPs
 CSRF
 CSV
+CacheClearCommand
 CacheInvalidator
 CacheInvalidatorS
 CachedProductListingRouteTest
@@ -586,6 +587,7 @@ MyPlugin
 MyTestClass
 MyTestInterface
 NATS
+NFS
 NPM
 NUR
 NVDA

guides/hosting/infrastructure/reverse-http-cache.md

@@ -37,7 +37,7 @@ It contains the Shopware default VCL (Varnish Configuration Language). The conta
 
 :::warning
 From version v6.6.x onwards, this method is deprecated and will be removed in v6.7.0.
-Utilising Varnish with Redis involves LUA scripts to determine URLs for the BAN request.
+Using Varnish with Redis involves LUA scripts to determine URLs for the BAN request.
 This can cause problems depending on the setup or network.
 Furthermore, Redis clusters are not supported.
 Therefore, it is advisable to opt for the [Varnish with `XKey`](#configure-varnish) integration instead.
@@ -76,17 +76,17 @@ Make sure to create a Symfony configuration to make it configurable again, as sh
 :::
 
 For the most part, using Symfony and Varnish doesn't cause any problem.
-But, when a request passes through a proxy, certain request information is sent using either the *standard Forwarded* header or *X-Forwarded* headers.
+But when a request passes through a proxy, certain request information is sent using either the *standard Forwarded* header or *X-Forwarded* headers.
 For example, instead of reading the `REMOTE_ADDR` header (which will now be the IP address of your reverse proxy), the user's true IP will be stored in a standard Forwarded: for="..." header or an *X-Forwarded-For* header.
 
 If you don't configure Symfony to look for these headers, you will get incorrect information about the client's IP address.
 Whether or not the client connects via HTTPS, the client's port and the hostname are requested.
 
-Go through [Proxies](https://symfony.com/doc/current/deployment/proxies.html) section for more information.
+Go through [the Proxies](https://symfony.com/doc/current/deployment/proxies.html) section for more information.
 
 ### Varnish Docker Image
 
-Shopware offers a Varnish Docker image that is pre-configured to work with Shopware.
+Shopware offers a Varnish Docker image pre-configured to work with Shopware.
 Find the [image](https://github.com/shopware/varnish-shopware) here.
 The image is based on the official Varnish image and contains the Shopware default VCL with few configurations as environment variables.
 
@@ -96,7 +96,7 @@ Varnish `XKey` is a cache key module that allows you to use Varnish with surroga
 It is a module not included in the default Varnish installation.
 It is available for Varnish 6.0 or higher.
 
-Checkout the official Varnish installation guide [here](https://github.com/varnish/varnish-modules#installation).
+Check out the official Varnish installation guide [here](https://github.com/varnish/varnish-modules#installation).
 
 And also needs to be enabled in the `config/packages/shopware.yml` file:
 
@@ -120,7 +120,7 @@ Make sure to replace the `__XXX__` placeholders with your actual values.
 The default configuration Varnish uses hard purges, so when you update a product, the page will be removed from the cache and the next request takes longer because the cache is empty.
 To avoid this, you can use soft purges.
 Soft purge keeps the old page in case and serves it still to the clients and refreshes the cache in the background.
-This way the client gets **always** a cached page and the cache is updated in the background.
+This way the client gets **always** a cached page, and the cache is updated in the background.
 
 To enable soft purge, you need to change the varnish configuration.
 
@@ -177,17 +177,17 @@ shopware:
 This feature has been introduced with Shopware version 6.4.15.0
 :::
 
-By default, the cache will be immediately purged and the next requesting user will get a slow response as the cache has been deleted.
+By default, the cache will be immediately purged, and the next requesting user will get a slow response as the cache has been deleted.
 On soft purge, the user still gets the cached response after the purge, but in the configured time interval, the cache will be refreshed.
 This makes sure that the client gets the fastest response possible.
 
 ```yaml
 # Be aware that the configuration key changed from `storefront.reverse_proxy` to `shopware.http_cache.reverse_proxy` starting with Shopware 6.6
 shopware:
   http_cache:
-    # Allow to serve the out-dated cache for 300 seconds
+    # Allow to serve the outdated cache for 300 seconds
     stale_while_revalidate: 300
-    # Allow to serve the out-dated cache for an hour if the origin server is offline
+    # Allow to serve the outdated cache for an hour if the origin server is offline
     stale_if_error: 3600
     reverse_proxy:
         enabled: true
@@ -214,9 +214,9 @@ 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 (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)
+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)
 
 If you only want to clear the http cache, use `bin/console cache:clear:http`
 

guides/hosting/installation-updates/deployments/build-w-o-db.md

@@ -1375,4 +1375,16 @@ 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.
+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 the 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.

guides/plugins/apps/app-base-guide.md

@@ -85,7 +85,7 @@ 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
@@ -109,8 +109,8 @@ This process is called setup.
 :::
 
 ::: warning
-Suppose your app makes use of the Admin Module, Payment Method, Tax providers or Webhook app system features.
-In that case, you need to implement the registration, to exchange a secret key; that is later used to authenticate the shops.
+Suppose your app makes use of the Admin Module, Payment Method, Tax providers, or Webhook app system features.
+In that case, you need to implement the registration to exchange a secret key; that is later used to authenticate the shops.
 :::
 
 During the setup, it is verified that Shopware connects to the right backend server and keys are exchanged to secure all further communications.
@@ -161,7 +161,7 @@ shopware-app-signature: a8830aface4ac4a21be94844426e62c77078ca9a10f694737b75ca15
 sw-version: 6.4.5.0
 ```
 
-Additionally, the `shopware-app-signature` header will be provided, which contains a cryptographic signature of the query string.  
+Additionally, the `shopware-app-signature` header will be provided, which contains a cryptographic signature of the query string.
 The secret used to generate this signature is the `app secret`, which is unique per app and will be provided by the Shopware Account if you upload your app to the store.
 This secret won't leave the Shopware Account, so it won't even be leaked to the shops installing your app.
 
@@ -317,7 +317,7 @@ Starting from Shopware version 6.4.1.0, the current Shopware version will be sen
 Starting from Shopware version 6.4.5.0, the current language id of the Shopware context will be sent as a  `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header.
 :::
 
-The request is signed with the `shop-secret` that your app provided in the [registration response](app-base-guide#registration-response) and the signature can be found in the `shopware-shop-signature` header.  
+The request is signed with the `shop-secret` that your app provided in the [registration response](app-base-guide#registration-response) and the signature can be found in the `shopware-shop-signature` header.
 You need to recalculate that signature and check that it matches the provided one to make sure that the request is really sent from the shop with that shopId.
 
 You can use the following code snippet to generate the signature:

guides/plugins/plugins/framework/caching/index.md

@@ -409,6 +409,20 @@ 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 and the object caches, and removes other kernel cache directories.
+
 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.
+
+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).
+:::