DoctrineBundle

https://symfony.com/bundles/DoctrineBundle/current/
Admin
DoctrineBundle integrates Doctrine ORM and DBAL into Symfony applications, providing configuration...
Tokens:14,576
Snippets:106
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install DoctrineBundle with Composer

Source: https://symfony.com/bundles/DoctrineBundle/current/installation.html

Run this command in your project directory to download the latest stable version of the bundle. Requires Composer to be installed globally.

```bash
$ composer require doctrine/doctrine-bundle
```

--------------------------------

### Get Help for doctrine:schema:update

Source: https://symfony.com/bundles/DoctrineBundle/current/doctrine-console.html

Displays help for the doctrine:schema:update command. Use this to get details about the command's options and arguments.

```bash
php bin/console doctrine:schema:update --help
```

--------------------------------

### AsDoctrineListener attribute example

Source: https://symfony.com/bundles/DoctrineBundle/current/event-listeners.html

Use the AsDoctrineListener attribute to tag a service as a Doctrine event listener. The attribute takes the event name, and optionally priority and connection. This example listens for the 'postPersist' event.

```php
// src/App/EventListener/SearchIndexer.php
namespace App\EventListener;

use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
use Doctrine\ORM\Event\LifecycleEventArgs;

#[AsDoctrineListener('postPersist'/*, 500, 'default'*/)]
class SearchIndexer
{
    public function postPersist(LifecycleEventArgs $event): void
    {
        // ...
    }
}
```

--------------------------------

### Configure Doctrine ORM entity manager with cache and listeners

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Configures the Doctrine ORM entity manager with cache drivers, entity listeners, and second-level cache settings. The entity manager uses the default naming and quote strategies, and the example shows an entity listener for the Author entity with a preUpdate event. The second-level cache is enabled with a region lock lifetime of 60 seconds and logging enabled.

```xml
<doctrine:orm default-entity-manager="default">

    <!-- example -->
    <doctrine:entity-manager
        name="default"
        connection=""
        class-metadata-factory-name="Doctrine\ORM\Mapping\ClassMetadataFactory"
        default-repository-class="Doctrine\ORM\EntityRepository"
        auto-mapping="false"
        naming-strategy="doctrine.orm.naming_strategy.default"
        quote-strategy="doctrine.orm.quote_strategy.default"
        typed-field-mapper="doctrine.orm.typed_field_mapper.default"
        entity-listener-resolver="null"
        repository-factory="null"
    >

        <doctrine:query-cache-driver
            type="pool"
            id=""
            pool=""
        />

        <doctrine:metadata-cache-driver
            type="pool"
            id=""
            pool=""
        />

        <doctrine:result-cache-driver
            type="pool"
            id=""
            pool=""
        />

        <doctrine:entity-listeners>

            <!-- example -->
            <doctrine:entity class="Acme\HelloBundle\Entity\Author">

                <!-- example -->
                <doctrine:listener class="Acme\HelloBundle\EventListener\ExampleListener">

                    <!-- example -->
                    <doctrine:event
                        type="preUpdate"
                        method="preUpdate"
                    />

                </doctrine:listener>

            </doctrine:entity>

        </doctrine:entity-listeners>

        <doctrine:second-level-cache
            region-lock-lifetime="60"
            log-enabled="true"
            region-lifetime="0"
            enabled="true"
            factory=""
        >

    </doctrine:entity-manager>

</doctrine:orm>
```

--------------------------------

### Using CustomIdGenerator with doctrine.uuid_generator

Source: https://symfony.com/bundles/DoctrineBundle/current/custom-id-generators.html

Example entity using the CustomIdGenerator attribute to reference the doctrine.uuid_generator service for UUID generation. Requires Doctrine bundle 2.3+ and Symfony's Uid component 5.3+.

```php
<?php
// User.php

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class User
{
    #[ORM\Id]
    #[ORM\Column(type: 'uuid')]
    #[ORM\GeneratedValue(strategy: 'CUSTOM')]
    #[ORM\CustomIdGenerator('doctrine.uuid_generator')]
    private $id;

    // ....
}
```

--------------------------------

### Autowire named connection by type-hinting Connection $purchaseLogsConnection

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Shows the before and after of a constructor signature when switching from a default connection to a named 'purchase_logs' connection. The first block is a placeholder line count; the second is the actual diff. Use the diff to change the type-hinted parameter name to match the connection name.

```text
1
2
3
4
5
```

```diff
-     public function __construct(Connection $connection)
+     public function __construct(Connection $purchaseLogsConnection)
    {
        $this->connection = $purchaseLogsConnection;
    }
```

--------------------------------

### List Doctrine Commands

Source: https://symfony.com/bundles/DoctrineBundle/current/doctrine-console.html

Lists all Doctrine commands registered by the bundle. Run this in the project root to see the available commands under the doctrine: namespace.

```bash
php bin/console list doctrine
```

--------------------------------

### Enable DoctrineBundle in config/bundles.php

Source: https://symfony.com/bundles/DoctrineBundle/current/installation.html

Add this line to the config/bundles.php file to manually enable the bundle when not using Flex. The bundle is automatically enabled by Flex in most cases.

```php
<?php
// config/bundles.php

return [
    // ...
    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
    // ...
];
```

--------------------------------

### Decorate the connect method to prevent root connections

Source: https://symfony.com/bundles/DoctrineBundle/current/middlewares.html

Extends AbstractDriverMiddleware to override the connect method. Throws a LogicException if the user is 'root'. Only the connect method needs to be decorated; other methods inherit default behavior.

```php
<?php

namespace App\Middleware;

use Doctrine\DBAL\Driver\Connection;
use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
use SensitiveParameter;

final class PreventRootConnectionDriver extends AbstractDriverMiddleware
{
    public function connect(array $params): Connection
    {
        if (isset($params['user']) && $params['user'] === 'root') {
            throw new \LogicException('Connecting to the database with the root user is not allowed.');
        }

        return parent::connect($params);
    }
}

```

--------------------------------

### Autowire a specific entity manager by type-hint

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Shows the before/after change for autowiring a specific entity manager. The diff replaces the constructor parameter type-hint with the named entity manager alias (e.g., $purchaseLogsEntityManager) and updates the assignment accordingly.

```text
1
2
3
4
5

```

```diff
-     public function __construct(EntityManagerInterface $entityManager)
+     public function __construct(EntityManagerInterface $purchaseLogsEntityManager)
    {
        $this->entityManager = $purchaseLogsEntityManager;
    }

```

--------------------------------

### Create a custom middleware class implementing Middleware

Source: https://symfony.com/bundles/DoctrineBundle/current/middlewares.html

Defines a middleware class that implements Doctrine\DBAL\Driver\Middleware. The wrap method decorates the driver with a custom driver class. This is the first step in creating a middleware that prevents root connections.

```php
<?php

namespace App\Middleware;

use Doctrine\DBAL\Driver;
use Doctrine\DBAL\Driver\Middleware;

class PreventRootConnectionMiddleware implements Middleware
{
    public function wrap(Driver $driver): Driver
    {
        return new PreventRootConnectionDriver($driver);
    }
}

```

--------------------------------

### Set middleware execution priority using AsMiddleware

Source: https://symfony.com/bundles/DoctrineBundle/current/middlewares.html

Adds the #[AsMiddleware(priority: 10)] attribute to ensure the middleware runs first. Higher priority means earlier execution; default priority is 0. This prevents debugging or logging if the connection is blocked.

```php
<?php

namespace App\Middleware;

use Doctrine\Bundle\DoctrineBundle\Attribute\AsMiddleware;
use Doctrine\DBAL\Driver;
use Doctrine\DBAL\Driver\Middleware;

#[AsMiddleware(priority: 10)]
class PreventRootConnectionMiddleware implements Middleware
{
    public function wrap(Driver $driver): Driver
    {
        return new PreventRootConnectionDriver($driver);
    }
}

```

--------------------------------

### Doctrine DBAL YAML configuration for multiple connections

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Configure multiple Doctrine DBAL connections in YAML under the `connections` key. The `default_connection` parameter selects the default connection; each connection is also accessible via the `doctrine.dbal.[name]_connection` service.

```yaml
doctrine:
    dbal:
        default_connection:       default
        connections:
            default:
                dbname:           Symfony2
                user:             root
                password:         null
                host:             localhost
            customer:
                dbname:           customer
                user:             root
                password:         null
                host:             localhost
```

--------------------------------

### Configure Doctrine DBAL connection with all attributes

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Defines a Doctrine DBAL connection with all available attributes. The default driver is pdo_mysql, and logging/profiling default to %kernel.debug%. Many attributes are optional and can be left empty.

```xml
<doctrine:connection
    name="default"
    dbname=""
    host="localhost"
    port="null"
    user="root"
    password="null"
    charset="null"
    path=""
    memory=""
    unix-socket=""
    persistent=""
    protocol=""
    service=""
    servicename=""
    sessionMode=""
    server=""
    default_dbname=""
    sslmode=""
    sslrootcert=""
    sslcert=""
    sslkey=""
    sslcrl=""
    pooled=""
    MultipleActiveResultSets=""
    driver="pdo_mysql"
    auto-commit=""
    schema-filter=""
    logging="%kernel.debug%"
    profiling="%kernel.debug%"
    profiling-collect-backtrace="false"
    profiling-collect-schema-errors="true"
    server-version=""
    driver-class=""
    wrapper-class=""
    keep-replica=""
>
```

--------------------------------

### Doctrine DBAL configuration keys (YAML)

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Shows all possible configuration keys for Doctrine DBAL under the doctrine.dbal key. Includes driver-specific options (e.g., PostgreSQL sslmode, Oracle service, SQLite path/memory) and Symfony-specific settings like logging and schema_filter. The comments indicate which options are specific to certain drivers or platforms.

```text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

```

```yaml
doctrine:
    dbal:
        url:                      mysql://user:secret@localhost:1234/otherdatabase
        dbname:                   database
        host:                     localhost
        port:                     1234
        user:                     user
        password:                 secret
        dbname_suffix:            _test
        driver:                   pdo_mysql
        driver_class:             MyNamespace\MyDriverImpl
        options:
            foo: bar
        path:                     "%kernel.project_dir%/var/data.db" # SQLite specific
        memory:                   true                               # SQLite specific
        unix_socket:              /tmp/mysql.sock
        persistent:               true
        MultipleActiveResultSets: true                # pdo_sqlsrv driver specific
        pooled:                   true                # Oracle specific (SERVER=POOLED)
        protocol:                 TCPIP               # IBM DB2 specific (PROTOCOL)
        server:                   my_database_server  # SQL Anywhere specific (ServerName)
        service:                  true                # Oracle specific (SERVICE_NAME instead of SID)
        servicename:              MyOracleServiceName # Oracle specific (SERVICE_NAME)
        sessionMode:              2                   # oci8 driver specific (session_mode)
        default_dbname:           database            # PostgreSQL specific (default_dbname)
        sslmode:                  require             # PostgreSQL specific (LIBPQ-CONNECT-SSLMODE)
        sslrootcert:              postgresql-ca.pem   # PostgreSQL specific (LIBPQ-CONNECT-SSLROOTCERT)
        sslcert:                  postgresql-cert.pem # PostgreSQL specific (LIBPQ-CONNECT-SSLCERT)
        sslkey:                   postgresql-key.pem  # PostgreSQL specific (LIBPQ-CONNECT-SSLKEY)
        sslcrl:                   postgresql.crl      # PostgreSQL specific (LIBPQ-CONNECT-SSLCRL)
        wrapper_class:            MyDoctrineConnectionWrapper
        charset:                  ~                   # RDBMS-specific. Refer to the manual of your RDBMS for more information.
        logging:                  "%kernel.debug%"
        platform_service:         MyDatabasePlatformService
        auto_commit:              false
        schema_filter:            /^sf2_/
        mapping_types:
            enum: string
        types:
            custom: Acme\HelloBundle\MyCustomType
        default_table_options:
            # Affects schema-tool. If absent, DBAL chooses defaults
            # based on the platform. These defaults might be
            # sub-optimal for backward compatibility reasons.
            charset:              utf8mb4
            collation:            utf8mb4_unicode_ci
            engine:               InnoDB

```

--------------------------------

### Enable DoctrineBundle in app/AppKernel.php

Source: https://symfony.com/bundles/DoctrineBundle/current/installation.html

For older Symfony versions without a config/bundles.php file, add the bundle to the registerBundles() method in app/AppKernel.php.

```php
<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...

            new Doctrine\Bundle\DoctrineBundle\DoctrineBundle(),
        ];

        // ...
    }

    // ...
}
```

--------------------------------

### DoctrineBundle DBAL Configuration Reference (YAML)

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Shows the full doctrine.dbal configuration structure with default_connection, custom types, and connection options for MySQL, SQLite, IBM DB2, Oracle, oci8, SQL Anywhere, and PostgreSQL. Use as a reference for configuring database connections in Symfony.

```yaml
doctrine:
    dbal:
        default_connection:           default

        # A collection of custom types
        types:
            # example
            some_custom_type:
                class:                Acme\HelloBundle\MyCustomType

        connections:
            # A collection of different named connections (e.g. default, conn2, etc)
            default:
                dbname:               ~
                host:                 localhost
                port:                 ~
                user:                 root
                password:             ~

                # RDBMS specific; Refer to the manual of your RDBMS for more information
                charset:              ~

                # Adds the given suffix to the configured database name, this option has no effects for the SQLite platform
                dbname_suffix:        ~

                # SQLite specific
                path:                 ~

                # SQLite specific
                memory:               ~

                # MySQL specific. The unix socket to use for MySQL
                unix_socket:          ~

                # IBM DB2 specific. True to use as persistent connection for the ibm_db2 driver
                persistent:           ~

                # IBM DB2 specific. The protocol to use for the ibm_db2 driver (default to TCPIP if omitted)
                protocol:             ~

                # Oracle specific. True to use SERVICE_NAME as connection parameter instead of SID for Oracle
                service:              ~

                # Oracle specific. Overrules dbname parameter if given and used as SERVICE_NAME or SID connection
                # parameter for Oracle depending on the service parameter.
                servicename:          ~

                # oci8 driver specific. The session mode to use for the oci8 driver.
                sessionMode:          ~

                # SQL Anywhere specific (ServerName). The name of a running database server to connect to for SQL Anywhere.
                server:               ~

                # PostgreSQL specific (default_dbname).
                # Override the default database (postgres) to connect to.
                default_dbname:       ~

                # PostgreSQL specific (LIBPQ-CONNECT-SSLMODE).
                # Determines whether or with what priority a SSL TCP/IP connection will be negotiated with the server for PostgreSQL.
                sslmode:              ~

                # PostgreSQL specific (LIBPQ-CONNECT-SSLROOTCERT).
                # The name of a file containing SSL certificate authority (CA) certificate(s).
                # If the file exists, the server's certificate will be verified to be signed by one of these authorities.
                sslrootcert:          ~

```

--------------------------------

### PHP service configuration for doctrine.event_listener

Source: https://symfony.com/bundles/DoctrineBundle/current/event-listeners.html

Register a service as a Doctrine event listener using the 'doctrine.event_listener' tag in PHP configuration. The 'event' option is required; 'priority' and 'connection' are optional.

```php
// config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\EventListener\SearchIndexer;

return static function (ContainerConfigurator $configurator) {
    $services = $configurator->services();

    // listeners are applied by default to all Doctrine connections
    $services->set(SearchIndexer::class)
        ->tag('doctrine.event_listener', [
            // this is the only required option for the lifecycle listener tag
            'event' => 'postPersist',

            // listeners can define their priority in case multiple subscribers or listeners are associated
            // to the same event (default priority = 0; higher numbers = listener is run earlier)
            'priority' => 500,

            // you can also restrict listeners to a specific Doctrine connection
            'connection' => 'default',
        ])
    ;
};
```

--------------------------------

### DoctrineBundle Configuration Reference (YAML)

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Full configuration reference for DoctrineBundle, showing all available options under the doctrine.dbal section. Includes driver-specific settings, schema filter, logging/profiling flags, result cache, and replica connection definitions.

```yaml
# PostgreSQL specific (LIBPQ-CONNECT-SSLCERT).
# The name of a file containing the client SSL certificate.
sslcert:              ~

# PostgreSQL specific (LIBPQ-CONNECT-SSLKEY).
# The name of a file containing the private key for the client SSL certificate.
sslkey:               ~

# PostgreSQL specific (LIBPQ-CONNECT-SSLCRL).
# The name of a file containing the SSL certificate revocation list (CRL).
sslcrl:               ~

# Oracle specific (SERVER=POOLED). True to use a pooled server with the oci8/pdo_oracle driver
pooled:               ~

# pdo_sqlsrv driver specific. Configuring MultipleActiveResultSets for the pdo_sqlsrv driver
MultipleActiveResultSets:  ~

driver:               pdo_mysql
platform_service:     ~
auto_commit:          ~

# If set to "/^sf2_/" all tables, and any named objects such as sequences
# not prefixed with "sf2_" will be ignored by the schema tool.
# This is for custom tables which should not be altered automatically.
schema_filter:        ~

# When true, queries are logged to a "doctrine" monolog channel
logging:              "%kernel.debug%"

profiling:            "%kernel.debug%"
# When true, profiling also collects a backtrace for each query
profiling_collect_backtrace: false
# When true, profiling also collects schema errors for each query
profiling_collect_schema_errors: true

server_version:       ~
driver_class:         ~
# Allows to specify a custom wrapper implementation to use.
# Must be a subclass of Doctrine\DBAL\Connection
wrapper_class:        ~
keep_replica:           ~

# An array of options
options:
    # example
    # key:                  value

# An array of mapping types
mapping_types:
    # example
    # enum:                 string

default_table_options:
    # Affects schema-tool. If absent, DBAL chooses defaults
    # based on the platform. Examples here are for MySQL.
    # charset:      utf8mb4
    # collation:    utf8mb4_unicode_ci
    # engine:       InnoDB

# Service identifier of a Psr\Cache\CacheItemPoolInterface implementation
# to use as the cache driver for dbal result sets.
result_cache:        ~

replicas:
    # A collection of named replica connections (e.g. replica1, replica2)
    replica1:
        dbname:               ~
        host:                 localhost
        port:                 ~
        user:                 root
        password:             ~
        charset:              ~

        # Adds the given suffix to the configured database name, this option has no effects for the SQLite platform
        dbname_suffix:        ~
        path:                 ~
        memory:               ~

        # MySQL specific. The unix socket to use for MySQL
        unix_socket:          ~

        # IBM DB2 specific. True to use as persistent connection for the ibm_db2 driver
        persistent:           ~

        # IBM DB2 specific. The protocol to use for the ibm_db2 driver (default to TCPIP if omitted)
        protocol:             ~

        # Oracle specific. True to use SERVICE_NAME as connection parameter instead of SID for Oracle
        service:              ~

        # Oracle specific. Overrules dbname parameter if given and used as SERVICE_NAME or SID connection
        # parameter for Oracle depending on the service parameter.
        servicename:          ~

        # oci8 driver specific. The session mode to use for the oci8 driver.
        sessionMode:          ~

        # SQL Anywhere specific (ServerName). The name of a running database server to connect to for SQL Anywhere.
        server:               ~
```

--------------------------------

### Set default table options (charset, collation, engine)

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Sets default table options for all tables: charset utf8mb4, collation utf8_unicode_ci, and engine InnoDB. These are applied when no explicit table option is given.

```xml
<doctrine:default-table-option name="charset">utf8mb4</doctrine:default-table-option>
<doctrine:default-table-option name="collation">utf8_unicode_ci</doctrine:default-table-option>
<doctrine:default-table-option name="engine">InnoDB</doctrine:default-table-option>
```

--------------------------------

### YAML service configuration for doctrine.event_listener

Source: https://symfony.com/bundles/DoctrineBundle/current/event-listeners.html

Register a service as a Doctrine event listener using the 'doctrine.event_listener' tag in YAML. The 'event' option is required; 'priority' and 'connection' are optional.

```yaml
# config/services.yaml
services:
    # ...

    App\EventListener\SearchIndexer:
        tags:
            -
                name: 'doctrine.event_listener'
                # this is the only required option for the lifecycle listener tag
                event: 'postPersist'

                # listeners can define their priority in case multiple subscribers or listeners are associated
                # to the same event (default priority = 0; higher numbers = listener is run earlier)
                priority: 500

                # you can also restrict listeners to a specific Doctrine connection
                connection: 'default'
```

--------------------------------

### XML service configuration for doctrine.event_listener

Source: https://symfony.com/bundles/DoctrineBundle/current/event-listeners.html

Register a service as a Doctrine event listener using the 'doctrine.event_listener' tag in XML. The 'event' attribute is required; 'priority' and 'connection' are optional.

```xml
<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
    <services>
        <!-- ... -->

        <!--
            * 'event' is the only required option that defines the lifecycle listener
            * 'priority': used when multiple subscribers or listeners are associated to the same event
            *             (default priority = 0; higher numbers = listener is run earlier)
            * 'connection': restricts the listener to a specific Doctrine connection
        -->
        <service id="App\EventListener\SearchIndexer">
            <tag name="doctrine.event_listener"
                event="postPersist"
                priority="500"
                connection="default"/>
        </service>
    </services>
</container>
```

--------------------------------

### Set driver-specific connection option

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Sets a driver-specific connection option. Replace 'key' and 'value' with the actual option name and value.

```xml
<doctrine:option key="key">value</doctrine:option>
```

--------------------------------

### Configure a Doctrine DBAL replica connection

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Configures a read replica connection for the Doctrine DBAL layer. The attributes cover driver-specific options such as dbname_suffix (ignored for SQLite), unix-socket for MySQL, persistent and protocol for ibm_db2, service/servicename for Oracle, sessionMode for oci8, server for SQL Anywhere, default_dbname and sslmode/sslrootcert/sslcert/sslkey/sslcrl for PostgreSQL, pooled for oci8/pdo_oracle, and MultipleActiveResultSets for pdo_sqlsrv.

```xml
<doctrine:replica
    name="replica1"
    dbname=""
    host="localhost"
    port="null"
    user="root"
    password="null"
    charset=""
    dbname_suffix=""
    path=""
    memory=""
    unix-socket=""
    persistent=""
    protocol=""
    service=""
    servicename=""
    sessionMode=""
    server=""
    default_dbname=""
    sslmode=""
    sslrootcert=""
    sslcert=""
    sslkey=""
    sslcrl=""
    pooled=""
    MultipleActiveResultSets=""
/>
```

--------------------------------

### Configure mapping for AcmeHelloBundle

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Configures a mapping for the AcmeHelloBundle. The mapping attribute is set to true, and other attributes like type, dir, alias, prefix, and is-bundle can be specified.

```xml
<!-- example -->
<doctrine:mapping
    name="AcmeHelloBundle"
    mapping="true"
    type=""
    dir=""
    alias=""
    prefix=""
    is-bundle=""
/>
```

--------------------------------

### Doctrine DBAL XML configuration for a single connection

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Configure a single Doctrine DBAL connection in XML. Includes driver-specific options for SQLite, Oracle, PostgreSQL, IBM DB2, SQL Anywhere, and oci8, plus custom types, mapping types, and default table options.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/doctrine
        http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">

    <doctrine:config>
        <!--
            SQLite specific options:
            - path
            - memory
        -->
        <!--
            Oracle specific options:
            - pooled (SERVER=POOLED)
            - service (SERVICE_NAME instead of SID)
            - servicename (SERVICE_NAME)
        -->
        <!--
            PostgreSQL specific options:
            - default_dbname (default_dbname)
            - sslmode (LIBPQ-CONNECT-SSLMODE)
            - sslrootcert (LIBPQ-CONNECT-SSLROOTCERT)
            - sslcert (LIBPQ-CONNECT-SSLCERT)
            - sslkey (LIBPQ-CONNECT-SSLKEY)
            - sslcrl (LIBPQ-CONNECT-SSLCRL)
        -->
        <!--
            IBM DB2 specific options:
            - protocol (PROTOCOL)
        -->
        <!--
            SQL Anywhere specific options:
            - server (ServerName)
        -->
        <!--
            oci8 specific options:
            - sessionMode (session_mode)
        -->

        <doctrine:dbal
            name="default"
            url="mysql://user:secret@localhost:1234/otherdatabase"
            dbname="database"
            host="localhost"
            port="1234"
            user="user"
            password="secret"
            driver="pdo_mysql"
            driver-class="MyNamespace\MyDriverImpl"
            path="%kernel.project_dir%/var/data.db"
            memory="true"
            unix-socket="/tmp/mysql.sock"
            persistent="true"
            multiple-active-result-sets="true"
            pooled="true"
            protocol="TCPIP"
            server="my_database_server"
            service="true"
            servicename="MyOracleServiceName"
            sessionMode="2"
            default_dbname="database"
            sslmode="require"
            sslrootcert="postgresql-ca.pem"
            sslcert="postgresql-cert.pem"
            sslkey="postgresql-key.pem"
            sslcrl="postgresql.crl"
            wrapper-class="MyDoctrineDbalConnectionWrapper"
            charset=""
            logging="%kernel.debug%"
            auto-commit="false"
            schema-filter="^sf2_"
        >
            <doctrine:option key="foo">bar</doctrine:option>
            <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
            <doctrine:default-table-option name="charset">utf8mb4</doctrine:default-table-option>
            <doctrine:default-table-option name="collation">utf8_unicode_ci</doctrine:default-table-option>
            <doctrine:default-table-option name="engine">InnoDB</doctrine:default-table-option>
            <doctrine:type name="custom">Acme\HelloBundle\MyCustomType</doctrine:type>
        </doctrine:dbal>
    </doctrine:config>
</container>
```

--------------------------------

### Doctrine caching drivers configuration

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Shows how to configure Doctrine caching drivers using the 'pool' type (with a cache pool defined in FrameworkBundle) and the 'service' type (with a custom service ID). The metadata_cache_driver defaults to a sane 'pool' configuration when not set.

```yaml
doctrine:
    orm:
        auto_mapping: true
        # With no cache set, this defaults to a sane 'pool' configuration
        metadata_cache_driver: ~
        # the 'pool' type requires to define the 'pool' option and configure a cache pool using the FrameworkBundle
        result_cache_driver:
            type: pool
            pool: doctrine.result_cache_pool
        # the 'service' type requires to define the 'id' option too
        query_cache_driver:
            type: service
            id: App\ORM\MyCacheService

framework:
    cache:
        pools:
            doctrine.result_cache_pool:
                adapter: cache.app
```

--------------------------------

### Doctrine ORM default configuration

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Shows the default ORM configuration values that Doctrine resolves to, including auto_mapping, default_entity_manager, and cache driver settings. Use as a baseline for understanding the defaults before customizing.

```yaml
doctrine:
    orm:
        auto_mapping: true
        # the standard distribution overrides this to be true in debug, false otherwise
        default_entity_manager: default
        metadata_cache_driver: ~
        query_cache_driver: ~
        result_cache_driver: ~
```

--------------------------------

### Register DQL string function test_string

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Registers a custom DQL string function named test_string, mapping it to the class Acme\HelloBundle\DQL\StringFunction.

```xml
<!-- example -->
<doctrine:string-function name="test_string">Acme\HelloBundle\DQL\StringFunction</doctrine:string-function>
```

--------------------------------

### Limit middleware scope to a specific connection using AsMiddleware

Source: https://symfony.com/bundles/DoctrineBundle/current/middlewares.html

Adds the #[AsMiddleware(connections: ['legacy'])] attribute to restrict the middleware to a connection named 'legacy'. This is useful when an application has multiple DBAL connections.

```php
<?php

namespace App\Middleware;

use Doctrine\Bundle\DoctrineBundle\Attribute\AsMiddleware;
use Doctrine\DBAL\Driver;
use Doctrine\DBAL\Driver\Middleware;

#[AsMiddleware(connections: ['legacy'])]
class PreventRootConnectionMiddleware implements Middleware
{
    public function wrap(Driver $driver): Driver
    {
        return new PreventRootConnectionDriver($driver);
    }
}

```

--------------------------------

### Oracle DB environment variables set by Doctrine

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Lists the environment variables that Doctrine changes in the Oracle DB session when the middleware is used. These formats are set to meet Doctrine requirements.

```text
NLS_TIME_FORMAT="HH24:MI:SS"
NLS_DATE_FORMAT="YYYY-MM-DD HH24:MI:SS"
NLS_TIMESTAMP_FORMAT="YYYY-MM-DD HH24:MI:SS"
NLS_TIMESTAMP_TZ_FORMAT="YYYY-MM-DD HH24:MI:SS TZH:TZM"
```

--------------------------------

### Map database type to Doctrine type

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Maps a database type (here 'enum') to a Doctrine type (here 'string'). Use this to override default type mappings.

```xml
<doctrine:mapping-type name="enum">string</doctrine:mapping-type>
```

--------------------------------

### Oracle DB middleware service configuration

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Defines a middleware service for Oracle DB to make Doctrine aware of the session environment format. Required when the Oracle environment format does not meet Doctrine requirements.

```yaml
services:
    oracle.middleware:
        class: Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession
        tags:
            - { name: doctrine.middleware, connection: default }
```

--------------------------------

### Register SQL filter with parameter

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Registers an SQL filter named some_filter with the required class attribute. The filter is disabled by default and includes a parameter foo_param with value bar_value.

```xml
<!-- example -->
<!-- Register SQL Filters in the entity manager -->
<!-- class: Required -->
<doctrine:filter
    name="some_filter"
    class="Acme\HelloBundle\Filter\SomeFilter"
    enabled="false"
>

    <!-- example -->
    <doctrine:parameter name="foo_param">bar_value</doctrine:parameter>

</doctrine:filter>
```

--------------------------------

### Register entity listener on entity with #[ORM\EntityListeners]

Source: https://symfony.com/bundles/DoctrineBundle/current/entity-listeners.html

Entity class using the #[ORM\EntityListeners] attribute to register a service-based entity listener. The listener service must be tagged with doctrine.orm.entity_listener to be automatically added to the resolver.

```php
<?php
// User.php

use Doctrine\ORM\Mapping as ORM;
use App\UserListener;

#[ORM\Entity]
#[ORM\EntityListeners([UserListener::class])]
class User
{
    // ....
}

```

--------------------------------

### Configure region cache driver with type pool

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Configures a cache driver for a region in the second-level cache. The type is set to "pool" and requires either an id or a pool attribute.

```xml
<doctrine:region-cache-driver
    type="pool"
    id=""
    pool=""
/>
```

--------------------------------

### Tag entity listener service in YAML with doctrine.orm.entity_listener

Source: https://symfony.com/bundles/DoctrineBundle/current/entity-listeners.html

YAML service definition tagging the listener with doctrine.orm.entity_listener. The entity_manager attribute is optional; the method attribute is optional and falls back to the subscribed event name.

```yaml
services:
    App\UserListener:
        tags:
            # Minimal configuration below
            - { name: doctrine.orm.entity_listener }
            # Or, optionally, you can give the entity manager name as below
            #- { name: doctrine.orm.entity_listener, entity_manager: custom }

```

--------------------------------

### Register DQL datetime function test_datetime

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Registers a custom DQL datetime function named test_datetime, mapping it to the class Acme\HelloBundle\DQL\DatetimeFunction.

```xml
<!-- example -->
<doctrine:datetime-function name="test_datetime">Acme\HelloBundle\DQL\DatetimeFunction</doctrine:datetime-function>
```

--------------------------------

### Define second-level cache region with cache driver

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Defines a second-level cache region with a default type, a lock path in the kernel cache directory, a lock lifetime of 60 seconds, and a lifetime of 0. It includes a nested cache driver of type pool.

```xml
<!-- example -->
<doctrine:region
    name=""
    lock-path="%kernel.cache_dir%/doctrine/orm/slc/filelock"
    lock-lifetime="60"
    type="default"
    lifetime="0"
    service=""
>

    <doctrine:cache-driver
        type="pool"
        id=""
        pool=""
    />

</doctrine:region>
```

--------------------------------

### Tag entity listener service in XML with doctrine.orm.entity_listener

Source: https://symfony.com/bundles/DoctrineBundle/current/entity-listeners.html

XML service definition tagging the listener with doctrine.orm.entity_listener and specifying event, entity, entity_manager, and method attributes. The event attribute is required if the listener is not registered on the entity; method falls back to the event name if omitted.

```xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <services>
        <service id="App\UserListener">
            <!-- entity_manager attribute is optional -->
            <!-- method attribute is optional -->
            <tag
                name="doctrine.orm.entity_listener" 
                event="preUpdate"
                entity="App\Entity\User"
                entity_manager="custom"
                method="validateEmail"
            />
        </service>
    </services>
</container>

```

--------------------------------

### Register second-level cache logger

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Registers a logger for the second-level cache. The service attribute specifies the logger service to use.

```xml
<!-- example -->
<doctrine:logger
    name=""
    service=""
/>
```

--------------------------------

### Register custom hydrator ListHydrator

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Registers a custom hydrator named ListHydrator, mapping it to the class Acme\HelloBundle\Hydrators\ListHydrator.

```xml
<!-- example -->
<doctrine:hydrator name="ListHydrator">Acme\HelloBundle\Hydrators\ListHydrator</doctrine:hydrator>
```

--------------------------------

### Doctrine filters configuration

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Defines a Doctrine filter in the configuration file. The filter identifier 'myFilter' is required, the 'class' is required, 'enabled' is optional (default disabled), and 'parameters' are optional key-value bindings.

```yaml
doctrine:
    orm:
        filters:
            myFilter:
                class: MyVendor\MyBundle\Filters\MyFilter
                enabled: true
                parameters:
                    myParameter: myValue
                    mySecondParameter: mySecondValue
```

--------------------------------

### Register DQL numeric function test_numeric

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Registers a custom DQL numeric function named test_numeric, mapping it to the class Acme\HelloBundle\DQL\NumericFunction.

```xml
<!-- example -->
<doctrine:numeric-function name="test_numeric">Acme\HelloBundle\DQL\NumericFunction</doctrine:numeric-function>
```

--------------------------------

### Ignore schema for entities Order and PhoneNumber

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Ignores the schema for two entities: Acme\AppBundle\Entity\Order and Acme\AppBundle\Entity\PhoneNumber. These are placed inside the entity-manager configuration.

```xml
<doctrine:schema-ignore-class>Acme\AppBundle\Entity\Order</doctrine:resolve-target-entity>
<doctrine:schema-ignore-class>Acme\AppBundle\Entity\PhoneNumber</doctrine:resolve-target-entity>
```

--------------------------------

### Register a custom Doctrine type in XML

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

XML configuration for the DoctrineBundle that registers a custom Doctrine type. The `class` attribute is required and must point to the custom type class. Use this snippet inside the `doctrine:dbal` section to define a custom type with a given name.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/doctrine
        http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">

    <doctrine:config>

        <doctrine:dbal default-connection="default">

            <!-- example -->
            <!-- class: Required -->
            <doctrine:type
                name="some_custom_type"
                class="Acme\HelloBundle\MyCustomType"
            />
```

--------------------------------

### Resolve target entity for InvoiceSubjectInterface

Source: https://symfony.com/bundles/DoctrineBundle/current/configuration.html

Resolves the target entity for the interface Acme\InvoiceBundle\Model\InvoiceSubjectInterface to the class Acme\AppBundle\Entity\Customer.

```xml
<!-- example -->
<doctrine:resolve-target-entity interface="Acme\InvoiceBundle\Model\InvoiceSubjectInterface">Acme\AppBundle\Entity\Customer</doctrine:resolve-target-entity>
```
Tokens:
Raw