From 8d3ec14c4ce865bf9cff0b70868b5411c5326e00 Mon Sep 17 00:00:00 2001 From: bidi47 Date: Tue, 17 Nov 2026 17:13:16 +0200 Subject: [PATCH 1/3] updated references to doctrine cache Signed-off-by: bidi47 --- .../v7/installation/configuration-files.md | 1 + docs/book/v7/installation/doctrine-orm.md | 64 ++++++++++++++++++- docs/book/v7/introduction/packages.md | 6 ++ .../book/v7/reference/production-readiness.md | 3 +- 4 files changed, 72 insertions(+), 2 deletions(-) diff --git a/docs/book/v7/installation/configuration-files.md b/docs/book/v7/installation/configuration-files.md index 3e2a9c88..7b2982e0 100644 --- a/docs/book/v7/installation/configuration-files.md +++ b/docs/book/v7/installation/configuration-files.md @@ -26,6 +26,7 @@ The installation script will duplicate the following files: > `local.php` is the main configuration file for your application. > It contains the database connection parameters, the API key, and other configuration items. +> It also holds the `$enableSecondLevelCache` flag, which is `false` by default; see [Second-level cache](doctrine-orm.md#second-level-cache). * `config/autoload/mail.local.php` from the `dot-mail` package installed in the `vendor` folder. diff --git a/docs/book/v7/installation/doctrine-orm.md b/docs/book/v7/installation/doctrine-orm.md index cb49bda5..ab374b6b 100644 --- a/docs/book/v7/installation/doctrine-orm.md +++ b/docs/book/v7/installation/doctrine-orm.md @@ -10,6 +10,7 @@ In this step you will: - [Save the database connection credentials in the API configuration file](#setup-database). - [Learn about table names prefixing](#understanding-table-names-prefixing). +- [Decide whether to enable the second-level cache](#second-level-cache). - [Create a migration](#creating-migrations). - [Run a migration](#running-migrations). - [Executing fixtures to populate your database](#executing-fixtures). @@ -63,12 +64,15 @@ You can switch to the 'postgresql' connection by commenting `'params' => $databa ```php 'doctrine' => [ - 'connection' => [ + 'connection' => [ 'orm_default' => [ 'params' => $databases['mariadb'], // 'params' => $databases['postgresql'], ], ], + 'configuration' => [ + // second-level cache, see below + ], ], ``` @@ -128,6 +132,53 @@ This feature helps organize databases and prevent naming conflicts if you plan o > `doctrine_migration_versions` is an exception and will remain unchanged, since it's a special table handled only by Doctrine Migrations. +### Second-level cache + +Starting with `doctrine/orm` 3.8.0, Doctrine's second-level cache needs the separate package `doctrine/orm-plugin-second-level-cache`. +The ORM only suggests that package, so Composer does not install it. +If the cache is enabled and the package is missing, the entity manager cannot be created and the first request fails with: + +```text +Service with name "doctrine.entity_manager.orm_default" could not be created. +Reason: Using the second level cache requires installing an additional package. +Install with composer require doctrine/orm-plugin-second-level-cache +``` + +The Core `ConfigProvider` turns the cache on by default. +`config/autoload/local.php` switches it off with the `$enableSecondLevelCache` flag, which loads after the Core configuration and overrides only the `enabled` key: + +```php +$enableSecondLevelCache = false; +``` + +```php +'doctrine' => [ + 'connection' => [ + // ... + ], + 'configuration' => [ + 'orm_default' => [ + 'second_level_cache' => [ + 'enabled' => $enableSecondLevelCache, + ], + ], + ], +], +``` + +The stock application does not use the second-level cache: no entity has `#[ORM\Cache]` and no query calls `setCacheable(true)`. +The query cache used by the repositories (`useQueryCache(true)`) is a separate cache and is not affected by this flag. + +To enable the second-level cache, install the plugin and then set the flag to `true`: + +```shell +composer require doctrine/orm-plugin-second-level-cache:^1.0 +``` + +> `config/autoload/local.php` is copied from `local.php.dist` only once, at install time. +> If your installation predates this flag, add the variable and the `configuration` block to your `local.php` by hand. +> If configuration caching is enabled, delete `data/cache/config-cache.php` afterwards. + ### Creating Migrations When first installing the application, you will need to create a database migration. @@ -264,6 +315,17 @@ That is only an example — use any name, as long as the configuration and the d A: It prepends a string to every table name from the entities, which keeps table sets apart when several applications share one database. The prefix is applied verbatim, with no separator added, and `doctrine_migration_versions` is left untouched because Doctrine Migrations owns it. +**Q: The first request fails with "Using the second level cache requires installing an additional package". What is wrong?** + +A: Composer installed `doctrine/orm` 3.8.0 or later, which needs `doctrine/orm-plugin-second-level-cache` for the second-level cache, and your configuration still enables that cache. +Add `$enableSecondLevelCache = false;` and the `doctrine.configuration.orm_default.second_level_cache.enabled` key to `config/autoload/local.php`, or install the plugin if you need the cache. +See [Second-level cache](#second-level-cache). + +**Q: Does disabling the second-level cache slow the application down?** + +A: Not in the stock application, which never stores entities in it. +It only matters if you add `#[ORM\Cache]` to entities or call `setCacheable(true)` on queries. + **Q: Why use migrations instead of editing the schema by hand?** A: Migrations make schema changes repeatable, trackable and safe to apply across environments. diff --git a/docs/book/v7/introduction/packages.md b/docs/book/v7/introduction/packages.md index 8de1e11c..d7a76f68 100644 --- a/docs/book/v7/introduction/packages.md +++ b/docs/book/v7/introduction/packages.md @@ -118,6 +118,12 @@ A: Because `composer.json` does not declare them. The application uses all three directly — Doctrine throughout the entities, repositories and migrations, and the service manager in `config/container.php` — but they are installed transitively as dependencies of the declared packages. Run `composer show ` to see the version you have. +**Q: Why did a `composer update` break the entity manager?** + +A: Because `doctrine/orm` is not pinned, an update can pull in a new minor release. +`doctrine/orm` 3.8.0 moved the second-level cache into the separate package `doctrine/orm-plugin-second-level-cache`, so an installation that still enables that cache fails on the first request. +See [Second-level cache](../installation/doctrine-orm.md#second-level-cache). + **Q: Why does `ramsey/uuid` require at least `4.5.0` specifically?** A: `4.5.0` is the release that added `Uuid::uuid7()`. diff --git a/docs/book/v7/reference/production-readiness.md b/docs/book/v7/reference/production-readiness.md index f9391d2c..6ab3f3e3 100644 --- a/docs/book/v7/reference/production-readiness.md +++ b/docs/book/v7/reference/production-readiness.md @@ -246,7 +246,8 @@ At the HTTP level there is no `ETag`, no `Last-Modified` and no conditional-requ Every other response leaves caching headers unset, which means intermediaries fall back to their own heuristics on responses that are usually per-identity. Set a conservative default under the `'*'` key in `config/autoload/response-header.global.php` and relax it only where you actually want caching. -Doctrine's second-level cache and result cache are not configured either, so a collection endpoint queries the database on every request. +Doctrine's result cache is not configured either, and the second-level cache is switched off by `$enableSecondLevelCache` in `config/autoload/local.php`, so a collection endpoint queries the database on every request. +Enabling the second-level cache on `doctrine/orm` 3.8 or later also requires `doctrine/orm-plugin-second-level-cache`; see [Second-level cache](../installation/doctrine-orm.md#second-level-cache). Issue #443 is the open RFC to extend caching in the API. ## Background work From 284243ef02ec22ed7e246dd9c12179c0e1886e37 Mon Sep 17 00:00:00 2001 From: bidi47 Date: Tue, 17 Nov 2026 17:43:04 +0200 Subject: [PATCH 2/3] updated references to doctrine cache Signed-off-by: bidi47 --- docs/book/v7/installation/configuration-files.md | 2 +- docs/book/v7/installation/doctrine-orm.md | 15 ++++++--------- docs/book/v7/reference/production-readiness.md | 2 +- 3 files changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/book/v7/installation/configuration-files.md b/docs/book/v7/installation/configuration-files.md index 7b2982e0..c7bcf7dd 100644 --- a/docs/book/v7/installation/configuration-files.md +++ b/docs/book/v7/installation/configuration-files.md @@ -26,7 +26,7 @@ The installation script will duplicate the following files: > `local.php` is the main configuration file for your application. > It contains the database connection parameters, the API key, and other configuration items. -> It also holds the `$enableSecondLevelCache` flag, which is `false` by default; see [Second-level cache](doctrine-orm.md#second-level-cache). +> It also switches off Doctrine's second-level cache (`doctrine.configuration.orm_default.second_level_cache.enabled` is `false`); see [Second-level cache](doctrine-orm.md#second-level-cache). * `config/autoload/mail.local.php` from the `dot-mail` package installed in the `vendor` folder. diff --git a/docs/book/v7/installation/doctrine-orm.md b/docs/book/v7/installation/doctrine-orm.md index ab374b6b..fd36ce50 100644 --- a/docs/book/v7/installation/doctrine-orm.md +++ b/docs/book/v7/installation/doctrine-orm.md @@ -145,11 +145,8 @@ Install with composer require doctrine/orm-plugin-second-level-cache ``` The Core `ConfigProvider` turns the cache on by default. -`config/autoload/local.php` switches it off with the `$enableSecondLevelCache` flag, which loads after the Core configuration and overrides only the `enabled` key: - -```php -$enableSecondLevelCache = false; -``` +`config/autoload/local.php` switches it off by setting the `enabled` key to `false`. +It loads after the Core configuration and overrides only that key, so the other second-level cache settings still come from Core: ```php 'doctrine' => [ @@ -159,7 +156,7 @@ $enableSecondLevelCache = false; 'configuration' => [ 'orm_default' => [ 'second_level_cache' => [ - 'enabled' => $enableSecondLevelCache, + 'enabled' => false, ], ], ], @@ -169,14 +166,14 @@ $enableSecondLevelCache = false; The stock application does not use the second-level cache: no entity has `#[ORM\Cache]` and no query calls `setCacheable(true)`. The query cache used by the repositories (`useQueryCache(true)`) is a separate cache and is not affected by this flag. -To enable the second-level cache, install the plugin and then set the flag to `true`: +To enable the second-level cache, install the plugin and then set `enabled` to `true`: ```shell composer require doctrine/orm-plugin-second-level-cache:^1.0 ``` > `config/autoload/local.php` is copied from `local.php.dist` only once, at install time. -> If your installation predates this flag, add the variable and the `configuration` block to your `local.php` by hand. +> If your installation predates this setting, add the `configuration` block to your `local.php` by hand. > If configuration caching is enabled, delete `data/cache/config-cache.php` afterwards. ### Creating Migrations @@ -318,7 +315,7 @@ The prefix is applied verbatim, with no separator added, and `doctrine_migration **Q: The first request fails with "Using the second level cache requires installing an additional package". What is wrong?** A: Composer installed `doctrine/orm` 3.8.0 or later, which needs `doctrine/orm-plugin-second-level-cache` for the second-level cache, and your configuration still enables that cache. -Add `$enableSecondLevelCache = false;` and the `doctrine.configuration.orm_default.second_level_cache.enabled` key to `config/autoload/local.php`, or install the plugin if you need the cache. +Set `doctrine.configuration.orm_default.second_level_cache.enabled` to `false` in `config/autoload/local.php`, or install the plugin if you need the cache. See [Second-level cache](#second-level-cache). **Q: Does disabling the second-level cache slow the application down?** diff --git a/docs/book/v7/reference/production-readiness.md b/docs/book/v7/reference/production-readiness.md index 6ab3f3e3..3ed7bc07 100644 --- a/docs/book/v7/reference/production-readiness.md +++ b/docs/book/v7/reference/production-readiness.md @@ -246,7 +246,7 @@ At the HTTP level there is no `ETag`, no `Last-Modified` and no conditional-requ Every other response leaves caching headers unset, which means intermediaries fall back to their own heuristics on responses that are usually per-identity. Set a conservative default under the `'*'` key in `config/autoload/response-header.global.php` and relax it only where you actually want caching. -Doctrine's result cache is not configured either, and the second-level cache is switched off by `$enableSecondLevelCache` in `config/autoload/local.php`, so a collection endpoint queries the database on every request. +Doctrine's result cache is not configured either, and the second-level cache is switched off in `config/autoload/local.php`, so a collection endpoint queries the database on every request. Enabling the second-level cache on `doctrine/orm` 3.8 or later also requires `doctrine/orm-plugin-second-level-cache`; see [Second-level cache](../installation/doctrine-orm.md#second-level-cache). Issue #443 is the open RFC to extend caching in the API. From 17d23f210ce335b33f94fe3534fe03946b736404 Mon Sep 17 00:00:00 2001 From: bidi47 Date: Wed, 18 Nov 2026 12:09:31 +0200 Subject: [PATCH 3/3] documented persistent connection Signed-off-by: bidi47 --- docs/book/v7/installation/doctrine-orm.md | 50 +++++++++++++++++++ .../book/v7/reference/production-readiness.md | 9 ++++ 2 files changed, 59 insertions(+) diff --git a/docs/book/v7/installation/doctrine-orm.md b/docs/book/v7/installation/doctrine-orm.md index fd36ce50..61fab9f6 100644 --- a/docs/book/v7/installation/doctrine-orm.md +++ b/docs/book/v7/installation/doctrine-orm.md @@ -10,6 +10,7 @@ In this step you will: - [Save the database connection credentials in the API configuration file](#setup-database). - [Learn about table names prefixing](#understanding-table-names-prefixing). +- [Decide whether to use persistent connections](#persistent-connections). - [Decide whether to enable the second-level cache](#second-level-cache). - [Create a migration](#creating-migrations). - [Run a migration](#running-migrations). @@ -34,6 +35,7 @@ $databases = [ 'password' => '', 'port' => 3306, 'driver' => 'pdo_mysql', + 'persistent' => false, 'collation' => 'utf8mb4_general_ci', 'table_prefix' => '', ], @@ -44,6 +46,7 @@ $databases = [ 'password' => '', 'port' => 5432, 'driver' => 'pdo_pgsql', + 'persistent' => false, 'collation' => 'utf8mb4_general_ci', 'table_prefix' => '', ], @@ -176,6 +179,42 @@ composer require doctrine/orm-plugin-second-level-cache:^1.0 > If your installation predates this setting, add the `configuration` block to your `local.php` by hand. > If configuration caching is enabled, delete `data/cache/config-cache.php` afterwards. +### Persistent connections + +Each entry in `$databases` has a `persistent` key, which is `false` by default. +Set it to `true` on the connection you use to keep the database connection open after a request ends, so the next request handled by the same PHP process reuses it instead of opening a new one. + +| Driver | `persistent` supported | +| --- | --- | +| `pdo_mysql`, `mysqli` | Yes | +| `pdo_pgsql` | Yes | +| `pgsql` | No | +| `pdo_sqlite`, `sqlite3` | No, the key is ignored | + +> Persistent connections for MySQL and PostgreSQL are first documented in `doctrine/dbal` 4.3 and 3.10. +> `doctrine/dbal` is installed as a dependency of other packages, so run `composer show doctrine/dbal` to check your version. +> Older versions ignore the key. + +Before you turn it on, check the following: + +- **Connection limit:** every PHP-FPM worker holds its own connection, so the database's `max_connections` must be higher than the total number of workers across every pool and server that connects to it. +- **Leftover state:** a reused connection keeps whatever the previous request left on it, such as an open transaction after a fatal error, session variables, temporary tables or locks. +- **Idle timeouts:** the database can close a connection that has been idle too long (MariaDB's `wait_timeout`), and the next request on that worker then fails with "server has gone away". +- **CLI:** commands gain nothing, because each one runs in its own process. +- **PostgreSQL:** a connection pooler such as PgBouncer is usually a better choice than persistent connections. + +To confirm that connections are reused, make a few requests and compare the connection IDs: + +```sql +-- MariaDB +SHOW PROCESSLIST; + +-- PostgreSQL +SELECT pid, backend_start FROM pg_stat_activity WHERE datname = 'dotkernel'; +``` + +> If your installation predates this setting, add `'persistent' => false,` to each entry in `$databases` in your `local.php` by hand. + ### Creating Migrations When first installing the application, you will need to create a database migration. @@ -312,6 +351,17 @@ That is only an example — use any name, as long as the configuration and the d A: It prepends a string to every table name from the entities, which keeps table sets apart when several applications share one database. The prefix is applied verbatim, with no separator added, and `doctrine_migration_versions` is left untouched because Doctrine Migrations owns it. +**Q: Should I enable persistent connections?** + +A: Only after checking that the database's `max_connections` covers every PHP-FPM worker that connects to it. +They save the cost of opening a connection on each request, but each worker then holds a connection permanently. +See [Persistent connections](#persistent-connections). + +**Q: I set `persistent` to `true`, but every request still opens a new connection. Why?** + +A: Check that you changed the entry that `doctrine.connection.orm_default.params` points to, that the driver is `pdo_mysql`, `mysqli` or `pdo_pgsql`, and that `doctrine/dbal` is at least 4.3 (or 3.10). +If configuration caching is enabled, delete `data/cache/config-cache.php`. + **Q: The first request fails with "Using the second level cache requires installing an additional package". What is wrong?** A: Composer installed `doctrine/orm` 3.8.0 or later, which needs `doctrine/orm-plugin-second-level-cache` for the second-level cache, and your configuration still enables that cache. diff --git a/docs/book/v7/reference/production-readiness.md b/docs/book/v7/reference/production-readiness.md index 3ed7bc07..c787fd71 100644 --- a/docs/book/v7/reference/production-readiness.md +++ b/docs/book/v7/reference/production-readiness.md @@ -250,6 +250,15 @@ Doctrine's result cache is not configured either, and the second-level cache is Enabling the second-level cache on `doctrine/orm` 3.8 or later also requires `doctrine/orm-plugin-second-level-cache`; see [Second-level cache](../installation/doctrine-orm.md#second-level-cache). Issue #443 is the open RFC to extend caching in the API. +## Database connections + +By default, each request opens a new database connection and closes it at the end. +The `persistent` key in each `$databases` entry of `config/autoload/local.php` lets PHP-FPM workers keep their connection open and reuse it, which saves the connection setup on every request. +It ships as `false`. +Before you set it to `true`, make sure the database's `max_connections` is higher than the total number of PHP-FPM workers that connect to it. +For PostgreSQL, a connection pooler such as PgBouncer is usually the better option. +See [Persistent connections](../installation/doctrine-orm.md#persistent-connections). + ## Background work Everything happens inside the request.