diff --git a/docs/infrastructure_and_maintenance/cache/persistence_cache.md b/docs/infrastructure_and_maintenance/cache/persistence_cache.md index 31b90099c5..0813792986 100644 --- a/docs/infrastructure_and_maintenance/cache/persistence_cache.md +++ b/docs/infrastructure_and_maintenance/cache/persistence_cache.md @@ -17,10 +17,8 @@ For details on how to reuse this Cache service in your own custom code, see belo ## Transparent cache -With the persistence cache, like with the HTTP cache, [[= product_name =]] tries to follow principles of transparent caching. -This can shortly be described as a cache which is invisible to the end user (admin/editors) of [[= product_name =]] where content is always returned *fresh*. -In other words, there should be no need to manually clear the cache like it was frequently the case with eZ Publish 4.x. -This is possible thanks to an interface that follows CRUD (Create Read Update Delete) operations per domain. +With the persistence cache, like with the HTTP cache, [[= product_name =]] follows the principles of transparent caching. +The cache is invisible to the end user (admin/editors) of [[= product_name =]] and content is always returned *fresh*. ## What is cached? @@ -46,11 +44,11 @@ To see where and how to contribute additional caches, refer to the [source code] !!! note - Current implementation uses Symfony cache. + Current implementation uses [Symfony application cache]([[= symfony_doc =]]/cache.html#system-cache-and-application-cache). It technically supports the following cache backends: [APCu, Array, Chain, Doctrine, Filesystem, PDO & Doctrine DBAL, Php Array, Proxy, Redis]([[= symfony_doc =]]/components/cache/cache_pools.html#creating-cache-pools). - [[= product_name =]] officially supports only using Filesystem for single server and Redis for clustered setups. + [[= product_name =]] officially supports only using Filesystem for single server and Redis/Valkey for clustered setups. -Use of Redis as shared cache back end is a requirement for use in clustering setup. +Use of [Redis/Valkey](#redisvalkey) as shared cache backend is a requirement for use in clustering setup. For an overview of this feature, see [Clustering](clustering.md). Filesystem adapters, for example, are **not** intended to be used over a shared filesystem. @@ -233,7 +231,7 @@ And as [[= product_name =]] requires that instances use a cluster-aware cache in #### With dependency injection -In your Symfony services configuration you can define that you require the cache service in your configuration like so: +In your Symfony services configuration you can inject the cache service in your configuration like so: ``` yaml # yml configuration @@ -244,33 +242,15 @@ In your Symfony services configuration you can define that you require the cache This service is an instance of `Symfony\Component\Cache\Adapter\TagAwareAdapterInterface`, which extends the `Psr\Cache\CacheItemPoolInterface` interface with tagging functionality. -#### With service container - -Like any other service, you can also get the cache service with the [service container](php_api.md#service-container) like so: - -``` php -use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface; -use Symfony\Component\DependencyInjection\ContainerInterface; - -// Getting the cache service in PHP - -/** @var ContainerInterface $container */ -$pool = $container->get('ibexa.cache_pool'); -/** @var TagAwareAdapterInterface $pool */ -``` - ### Using the cache service Example usage of the cache service: ``` php use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface; -use Symfony\Component\DependencyInjection\ContainerInterface; -// Example /** * @var TagAwareAdapterInterface $pool - * @var ContainerInterface $container * @var int $id */ $cacheItem = $pool->getItem("myApp-object-{$id}"); @@ -278,7 +258,7 @@ if ($cacheItem->isHit()) { return $cacheItem->get(); } -$myObject = $container->get('my_app.backend_service')->loadObject($id); +$myObject = $myAppCustomService->loadObject($id); $cacheItem->set($myObject); $cacheItem->tag(['myApp-category-' . $myObject->categoryId]); $pool->save($cacheItem); @@ -290,21 +270,8 @@ For more info on usage, see [Symfony Cache's documentation]([[= symfony_doc =]]/ ### Clearing persistence cache -!!! caution "Always clear the persistence with `cache:pool:clear` command" - - Running `php bin/console cache:clear` doesn't clear the persistence cache, even when you use a filesystem-based cache pool. - - You must always clear the persistence cache by running: - - ```bash - php bin/console cache:pool:clear - ``` - - The default cache pool is named `cache.tagaware.filesystem`. - The default cache pool when running Redis or Valkey is named `cache.redis`. - If you have customized the persistence cache configuration, the name of your cache pool might be different. - -Persistence cache prefixes it's cache using "ibx-". Clearing persistence cache can thus be done in the following ways: +Persistence cache uses the `ibx-` prefix, declared as a container parameter called `ibexa.core.persistence.cache.tag_prefix`. +You can clear the cache as in the following example: ``` php use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface; @@ -322,3 +289,5 @@ $pool->deleteItems(["ibx-ci-$contentId"]); // Symfony cache is tag-based, so you can clear all cache related to a content item like this: $pool->invalidateTags(["c-$contentId"]); ``` + +To learn how to clear persistence cache when not using the PHP API, see [Clear persistence cache](devops.md#clear-persistence-cache). diff --git a/docs/infrastructure_and_maintenance/devops.md b/docs/infrastructure_and_maintenance/devops.md index 53378b18d3..2fb47269b5 100644 --- a/docs/infrastructure_and_maintenance/devops.md +++ b/docs/infrastructure_and_maintenance/devops.md @@ -6,34 +6,73 @@ description: See various tools that can help you debug your Ibexa DXP installati ## Cache clearing -### Clearing file cache using the Symfony cache:clear command +[[= product_name =]] contains multiple layer of caching that you can clear independently from each other: -Symfony provides a command for clearing cache. -It deletes all file-based caches, which mainly consist of a Twig template, a [service container](php_api.md#service-container), and the Symfony route cache, but also everything else stored in the cache folder. -Out of the box on a single-server setup this includes Content cache. +- [Clear system cache](#clear-system-cache) +- [Clear persistence cache](#clear-persistence-cache) +- [Clear HTTP cache](#clear-http-cache) -For further information on the command's use, see its help text: +### Clear system cache + +[System cache]([[= symfony_doc =]]/cache.html#system-cache-and-application-cache) is separate for every [Symfony environment](environments.md) and stores information derivable from source code like compiled container, routes, or optimized classes. + +To clear the system cache, execute the `cache:clear` command on [every web server](clustering.md) running [[= product_name =]]. + +To specify an environment, pass it by using either the `--env` option or the `APP_ENV` variable. +Both the examples below clear the system cache for the `prod` environment: + +- `APP_ENV=prod php bin/console cache:clear` +- `php bin/console cache:clear --env=prod` + +When neither the `--env` option nor the `APP_ENV` variable is set, `cache:clear` clears the system cache for the `dev` environment by default. + +Don't run `cache:clear` as root as it can lead to issues with file ownership. + +!!! caution "Symfony 7.4 behavior change" + + Starting with Symfony 7.4, running `php bin/console cache:clear` or `rm -rf var/cache/*` clears only the system cache, even when you use a filesystem-based cache pool for [persistence cache](#clear-persistence-cache). + You must always clear the persistence cache separately. + +#### Clearing system cache manually + +During development, you can clear the system cache manually by running: ``` bash -php bin/console --env=prod cache:clear -h +rm -rf var/cache/* ``` -!!! note +!!! caution "Don't clear system cache manually on production" - If you don't specify an environment, by default `cache:clear` clears the cache for the `dev` environment. - If you want to clear it for `prod` you need to use the `--env=prod` option. + Manually clearing the system cache doesn't warm up the cache, resulting in a significant performance drop on the first request. + To avoid this, you must not clear the cache manually in a production environment. -!!! caution "Clustering" +### Clear persistence cache - In [clustering](clustering.md) setup (with several web servers), the command to clear file cache needs to be executed on every web server. +[Persistence cache](persistence_cache.md) stores information about application data. + +To clear the persistence cache, you must run: + +``` bash +php bin/console cache:pool:clear +``` + +The default cache pool is named `cache.tagaware.filesystem`. +The default cache pool when running Redis or Valkey is named `cache.redis`. +If you customized the persistence cache configuration, the name of your cache pool might be different. + +#### Clearing persistence cache manually + +During development, when using a filesystem-based cache pool, you can clear the application cache by running: + +```bash +rm -rf var/share/* +``` -### Clearing content cache on a cluster setup +### Clear HTTP cache -For a [cluster](clustering.md) setup, the content cache ([HTTP cache](http_cache.md) and [Persistence cache](persistence_cache.md)) must be set up to be shared among the servers. -While all relevant cache is cleared for you on repository changes when using the APIs, there might be times where you need to clear cache manually: +[HTTP cache](http_cache.md) uses reverse proxies like Varnish or Fastly to store application responses controlled by [HTTP Cache headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control). -- Varnish: [Cache purge](reverse_proxy.md#using-varnish-or-fastly) -- Persistence Cache: [Using Cache service](persistence_cache.md#using-cache-service) +To clear the HTTP cache, see [Purging from command line](content_aware_cache.md#purging-from-command-line). ## Web Debug Toolbar @@ -41,7 +80,7 @@ As of [[= product_name =]] v4.5, the [Symfony Web Debug Toolbar]([[= symfony_doc To install it, run the following command: ```bash -composer require symfony/debug-pack +composer require --dev symfony/debug-pack ``` After you have installed Symfony Web Debug Toolbar, it's available when running [[= product_name =]] in the `dev` environment. diff --git a/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md b/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md index 9255d2cfeb..ed2a13e3fa 100644 --- a/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md +++ b/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md @@ -56,34 +56,7 @@ They can be manually removed from `composer.json` now. ## How to clear the cache properly? -Clearing cache is covered by our [documentation](devops.md#cache-clearing), it applies to file and content (HTTP/persistence) cache. - -Useful commands: - -- clearing Symfony cache - -```bash -php bin/console cache:clear --env prod -``` - -- clearing Redis/Valkey cache - -```bash -php bin/console cache:pool:clear cache.redis -``` - -- clearing the Symfony cache manually - -```bash -rm -rf var/cache/* -rm -rf var/share/* -``` - -!!! caution "Clearing cache manually" - - Manual cache clearing should be executed with caution, as it doesn't warm up the cache. - It results in a significant performance drop on first request, so it shouldn't be called on a production environment. - Besides, it could lead to issues with file ownership after running `cache:clear` as a root. +See [Cache clearing](devops.md#cache-clearing) for information how to clear system, persistence, and HTTP caches. ## Where should I place my configuration files? diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index b4fd4b072c..c93bf5f5c1 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -67,10 +67,10 @@ parameters: path: code_samples/_inline_php/content_management/field_types/type_and_value/4d9e52e02d6e226f71015653d598f662f6b4d4eb0af9e99b4c49d5389af19671.php - - message: '#^Call to an undefined method object\:\:loadObject\(\)\.$#' - identifier: method.notFound + message: '#^Variable \$myAppCustomService might not be defined\.$#' + identifier: variable.undefined count: 1 - path: code_samples/_inline_php/infrastructure_and_maintenance/cache/persistence_cache/2f333548247830523074f882c44ffb2c58e158accf9fdcd50dcb4e2e86209b1f.php + path: code_samples/_inline_php/infrastructure_and_maintenance/cache/persistence_cache/c27a2fe1c12bba3e9271acc67ae3a2e2d4596bf58f4d9b791aec4e564ae88259.php - message: '#^Property App\\MyService\:\:\$contentService is never read, only written\.$#'