DOCSEARCHbyAlgolia
Submit Docs

Doctrine Bundle Documentation

repository·3.3.x·Indexed 26 days ago

https://github.com/doctrine/doctrinebundle

Official integration of Doctrine DBAL and ORM for the Symfony Framework. Provides configuration for database persistence, including DBAL connections, ORM entity managers, custom ID generators (UUID/ULID), mapping options, and RDBMS-specific settings for PostgreSQL, MySQL, Oracle, SQLite, IBM DB2, and SQL Anywhere.

Tokens
12.4K
Snippets
33
Records
77
Agent score
89%

What's inside DoctrineBundle

  1. Overview of Doctrine Bundle

    3.3.x
    Doctrine Bundle provides the integration for Doctrine DBAL (Database Abstraction Layer) and Doctrine ORM (Object Relational Mapper) within the Symfony Framework. It allows Symfony applications to leverage Doctrine's persistence services, including the ability to use Doctrine Query Language (DQL) for object-oriented database queries.

  2. Integrate Doctrine ORM and DBAL into Symfony

    3.3.x
    DoctrineBundle provides the integration layer for using Doctrine's Object-Relational Mapper (ORM) and Database Abstraction Layer (DBAL) within a Symfony application. It enables configuration of database connections, provides CLI commands for database management, and integrates with the Symfony web debug toolbar.

  3. Autowire specific Doctrine DBAL connections

    3.3.x

    When using multiple connections, you can autowire a specific connection into your services by using a specific type-hinting pattern: Doctrine\DBAL\Connection $<connection_name>Connection.

    For example, if you have a connection named purchase_logs, you should type-hint it as $purchaseLogsConnection (using camelCase for the variable name) to ensure the correct connection is injected.

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

  4. Enable DoctrineBundle manually in config/bundles.php

    3.3.x

    If you are not using Symfony Flex, you must manually register the bundle by adding Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class to your config/bundles.php file with the 'all' => true configuration.

    <?php
// config/bundles.php

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

  5. Remove deprecated enable_native_lazy_objects configuration

    3.3.x
    The configuration option doctrine.orm.entity_managers.{em_name}.enable_native_lazy_objects is deprecated in DoctrineBundle 3.1 and will be removed in version 4.0. Native lazy objects are now always enabled by default. You should remove this key from your configuration to prepare for the 4.0 upgrade.

  6. Enable the new `report_fields_where_declared` mapping driver mode

    3.3.x

    Doctrine ORM 2.16+ changed how annotation and attribute mapping drivers report inherited fields. To avoid deprecation notices and prepare for ORM 3.0 (where this mode becomes mandatory), you can opt-in to the new mode in DoctrineBundle 2.10+ by setting report_fields_where_declared to true in your entity manager configuration. This setting only affects mapping configurations using attributes or annotations.

    Note: While this should not affect valid use cases, it may trigger MappingExceptions if your current configuration relies on unsupported inheritance patterns.

  7. Upgrade to DoctrineBundle 3.0

    3.3.x

    When upgrading from version 2.x to 3.0, note the following breaking changes:

    • PHP Version: The minimum required PHP version is now 8.4.
    • Caching: Configuring caching options to use services backed by doctrine/cache is no longer supported. Migrate to PSR-6 services instead.
    • Dropped Package Support:
      • doctrine/dbal 3
      • doctrine/persistence 3
      • doctrine/orm 2
      • psr/log 1 and 2
      • twig/twig 2
    • ORM Changes: Support for YML and annotation metadata drivers is dropped. LazyServiceEntityRepository has been removed.

  8. Register custom DBAL types using the AsDbalType attribute

    3.3.x

    You can automatically register custom DBAL types by adding the #[AsDbalType] attribute to a class that extends Doctrine\DBAL\Types\Type. If you provide a name argument to the attribute, that name will be used as the type identifier in Doctrine. If no name is provided, the class name will be used as the default.

    namespace App\Doctrine\Type;

use Doctrine\Bundle\DoctrineBundle\Attribute\AsDbalType;
use Doctrine\DBAL\Platforms\AbstractPlatform;
use Doctrine\DBAL\Types\Type;

#[AsDbalType(name: 'money')]
class MoneyType extends Type
{
    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        return $platform->getDecimalTypeDeclarationSQL($column);
    }

    public function convertToPHPValue(mixed $value, AbstractPlatform $platform): mixed
    {
        return $value;
    }

    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): mixed
    {
        return $value;
    }
}

  9. Register Doctrine Event Listeners using PHP Attributes

    3.3.x

    Starting with Doctrine Bundle 2.8, you can use the #[AsDoctrineListener] attribute to automatically register a service as an event listener. This is the recommended way to register listeners in modern Symfony applications.

    Arguments for #[AsDoctrineListener]:

    • event (string): The name of the event to listen to (e.g., 'postPersist'). This is the only required argument.
    • priority (int, optional): Defines the execution order. Higher numbers are run earlier. Default is 0.
    • connection (string, optional): Restricts the listener to a specific Doctrine connection name (e.g., 'default').
    // 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
    {
        // ...
    }
}

  11. Configure Oracle DB session environment via middleware

    3.3.x

    If your Oracle DB environment format does not meet Doctrine requirements, you can use a middleware to ensure Doctrine is aware of the correct format. Register the Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession class as a service tagged with doctrine.middleware for your specific connection.

    This middleware sets the following environment variables in the Oracle DB session:

    • 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"
    services:
    oracle.middleware:
        class: Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession
        tags:
            - { name: doctrine.middleware, connection: default }

  12. Enable DoctrineBundle in older Symfony versions (AppKernel.php)

    3.3.x

    If your project does not have a config/bundles.php file (indicating an older Symfony version), you must manually register the bundle in app/AppKernel.php by adding a new instance of Doctrine\Bundle\DoctrineBundle\DoctrineBundle to the $bundles array within the registerBundles() method.

    <?php
// app/AppKernel.php

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

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

        // ...
    }

    // ...
}