Doctrine ORM

https://github.com/doctrine/orm
Admin
Doctrine ORM is an object-relational mapper for PHP that provides transparent persistence for PHP...
Tokens:570,829
Snippets:3,751
Trust Score:9.7
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Install SQLite on Debian-based Linux

Source: https://github.com/doctrine/orm/blob/3.7.x/tests/README.markdown

Install SQLite using apt-get, which is the easiest database vendor to set up for the tests.

```bash
sudo apt-get install sqlite
```

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

### HTML template example with CursorPaginator

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/pagination.rst

PHP template example that reads the cursor from the query string and creates a query for BlogPost ordered by createdAt and id descending. The example is incomplete; it only shows the setup and does not include the rendering of navigation links.

```php
<?php

use Doctrine\ORM\Tools\Pagination\CursorPaginator;

$cursor = $_GET['cursor'] ?? null;

$query = $entityManager->createQuery('SELECT p FROM BlogPost p ORDER BY p.createdAt DESC, p.id DESC');
```

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

### Install Doctrine with Composer

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Run this command in the project directory to install the packages defined in composer.json.

```bash
$ composer install
```

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

### Clone, install, and run tests

Source: https://github.com/doctrine/orm/blob/3.7.x/tests/README.markdown

Commands to clone the Doctrine ORM repository, install dependencies with Composer, and execute the test suite with PHPUnit.

```bash
git clone git@github.com:doctrine/orm.git
cd orm
composer install
./vendor/bin/phpunit
```

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

### OrderBy attribute example (incomplete)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Incomplete example for the #[OrderBy] attribute; only shows the opening PHP tag and a use statement for SortDirection.

```php
<?php

use SortDirection;
```

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

### Setup tool cache implementation diff

Source: https://github.com/doctrine/orm/blob/3.7.x/UPGRADE.md

Shows the change needed to pass a cache instance to the setup tool configuration factory. The old line is replaced with wrapping a PSR-6 implementation and passing it as the fourth argument.

```diff
- $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode, $proxyDir);
+ $cache = \Doctrine\Common\Cache\Psr6\DoctrineProvider::wrap($anyPsr6Implementation);
+ $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode, $proxyDir, $cache);
```

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

### Clone and install Doctrine ORM for testing

Source: https://github.com/doctrine/orm/blob/3.7.x/CONTRIBUTING.md

Commands to clone the Doctrine ORM repository and install dependencies with Composer, required before running the unit tests.

```sh
git clone git@github.com:doctrine/orm.git
cd orm
composer install
```

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

### Custom naming strategy implementation example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/namingstrategy.rst

A complete example of a custom naming strategy that prefixes table names with 'MyApp_', uses property names as column names, and generates join column and table names in lowercase. This implements the NamingStrategy interface.

```php
<?php
class MyAppNamingStrategy implements NamingStrategy
{
    public function classToTableName(string $className): string
    {
        return 'MyApp_' . substr($className, strrpos($className, '\\') + 1);
    }
    public function propertyToColumnName(string $propertyName): string
    {
        return $propertyName;
    }
    public function referenceColumnName(): string
    {
        return 'id';
    }
    public function joinColumnName(string $propertyName, ?string $className = null): string
    {
        return $propertyName . '_' . $this->referenceColumnName();
    }
    public function joinTableName(string $sourceEntity, string $targetEntity, string $propertyName): string
    {
        return strtolower($this->classToTableName($sourceEntity) . '_' .
                $this->classToTableName($targetEntity));
    }
    public function joinKeyColumnName(string $entityName, ?string $referencedColumnName): string
    {
        return strtolower($this->classToTableName($entityName) . '_' .
                ($referencedColumnName ?: $this->referenceColumnName()));
    }
}
```

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

### Serve documentation with PHP built-in server

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/README.md

Change to the output directory and start a PHP web server on localhost:8000 to browse the generated documentation.

```bash
cd docs/output
php -S localhost:8000
```

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

### Entity listener resolver example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Example of specifying an entity listener instance using the #[EntityListeners] attribute on an entity class.

```php
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

// User.php

#[Entity]
#[EntityListeners(["UserListener"])
class User
{
    // ....
}
```

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

### Set up Doctrine Console with bin/doctrine

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/tools.rst

Example of a project-specific bin/doctrine binary that registers custom commands and runs the Doctrine Console with a SingleManagerProvider. Requires a bootstrap file and an EntityManager instance.

```php
#!/usr/bin/env php
<?php

use Doctrine\ORM\Tools\Console\ConsoleRunner;
use Doctrine\ORM\Tools\Console\EntityManagerProvider\SingleManagerProvider;

// replace with path to your own project bootstrap file
require_once 'bootstrap.php';

// replace with mechanism to retrieve EntityManager in your app
$entityManager = GetEntityManager();

$commands = [
    // If you want to add your own custom console commands,
    // you can do so here.
];

ConsoleRunner::run(
    new SingleManagerProvider($entityManager),
    $commands
);
```

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

### QueryBuilder method signatures with inline usage examples

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Documented method signatures for the QueryBuilder class, each with inline comment examples showing typical usage. The examples illustrate the API for building DQL queries, including joins with conditions and indexBy, where clauses with expressions, grouping, having, and ordering. Note the comments about overrides and defaults, such as `where()` overriding previous conditions and `addOrderBy()` defaulting to 'ASC'.

```php
        // Example - $qb->from('Phonenumber', 'p')
        // Example - $qb->from('Phonenumber', 'p', 'p.id')
        public function from($from, $alias, $indexBy = null);

        // Example - $qb->join('u.Group', 'g', Expr\Join::WITH, $qb->expr()->eq('u.status_id', '?1'))
        // Example - $qb->join('u.Group', 'g', 'WITH', 'u.status = ?1')
        // Example - $qb->join('u.Group', 'g', 'WITH', 'u.status = ?1', 'g.id')
        public function join($join, $alias, $conditionType = null, $condition = null, $indexBy = null);

        // Example - $qb->innerJoin('u.Group', 'g', Expr\Join::WITH, $qb->expr()->eq('u.status_id', '?1'))
        // Example - $qb->innerJoin('u.Group', 'g', 'WITH', 'u.status = ?1')
        // Example - $qb->innerJoin('u.Group', 'g', 'WITH', 'u.status = ?1', 'g.id')
        public function innerJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null);

        // Example - $qb->leftJoin('u.Phonenumbers', 'p', Expr\Join::WITH, $qb->expr()->eq('p.area_code', 55))
        // Example - $qb->leftJoin('u.Phonenumbers', 'p', 'WITH', 'p.area_code = 55')
        // Example - $qb->leftJoin('u.Phonenumbers', 'p', 'WITH', 'p.area_code = 55', 'p.id')
        public function leftJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null);

        // NOTE: ->where() overrides all previously set conditions
        //
        // Example - $qb->where('u.firstName = ?1', $qb->expr()->eq('u.surname', '?2'))
        // Example - $qb->where($qb->expr()->andX($qb->expr()->eq('u.firstName', '?1'), $qb->expr()->eq('u.surname', '?2')))
        // Example - $qb->where('u.firstName = ?1 AND u.surname = ?2')
        public function where($where);

        // NOTE: ->andWhere() can be used directly, without any ->where() before
        //
        // Example - $qb->andWhere($qb->expr()->orX($qb->expr()->lte('u.age', 40), 'u.numChild = 0'))
        public function andWhere($where);

        // Example - $qb->orWhere($qb->expr()->between('u.id', 1, 10));
        public function orWhere($where);

        // NOTE: -> groupBy() overrides all previously set grouping conditions
        //
        // Example - $qb->groupBy('u.id')
        public function groupBy($groupBy);

        // Example - $qb->addGroupBy('g.name')
        public function addGroupBy($groupBy);

        // NOTE: -> having() overrides all previously set having conditions
        //
        // Example - $qb->having('u.salary >= ?1')
        // Example - $qb->having($qb->expr()->gte('u.salary', '?1'))
        public function having($having);

        // Example - $qb->andHaving($qb->expr()->gt($qb->expr()->count('u.numChild'), 0))
        public function andHaving($having);

        // Example - $qb->orHaving($qb->expr()->lte('g.managerLevel', '100'))
        public function orHaving($having);

        // NOTE: -> orderBy() overrides all previously set ordering conditions
        //
        // Example - $qb->orderBy('u.surname', \SortDirection::Descending)
        public function orderBy($sort, $order = null);

        // Example - $qb->addOrderBy('u.firstName')
        public function addOrderBy($sort, $order = null); // Default $order = 'ASC'
```

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

### preFlush listener example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Example of a preFlush event listener. Called inside EntityManager::flush() before anything else. Do not call flush() inside this listener to avoid infinite loop.

```php
<?php
use Doctrine\ORM\Event\PreFlushEventArgs;

class PreFlushExampleListener
{
    public function preFlush(PreFlushEventArgs $args)
    {
        // ...
    }
}
```

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

### List of QueryBuilder helper methods

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

A summary of the most commonly used helper methods and their usage examples.

```php
<?php
class QueryBuilder
{
    // Example - $qb->select('u')
    // Example - $qb->select(array('u', 'p'))
    // Example - $qb->select($qb->expr()->select('u', 'p'))
    public function select($select = null);

    // addSelect does not override previous calls to select
    //
    // Example - $qb->select('u');
    //              ->addSelect('p.area_code');
    public function addSelect($select = null);

    // Example - $qb->delete('User', 'u')
    public function delete($delete = null, $alias = null);

    // Example - $qb->update('Group', 'g')
    public function update($update = null, $alias = null);

    // Example - $qb->set('u.firstName', $qb->expr()->literal('Arnold'))
    // Example - $qb->set('u.numChilds', 'u.numChilds + ?1')
    // Example - $qb->set('u.numChilds', $qb->expr()->sum('u.numChilds', '?1'))
    public function set($key, $value);
}
```

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

### Start lock agent worker

Source: https://github.com/doctrine/orm/blob/3.7.x/tests/README.markdown

Command to start a Gearman worker for testing lock support in the Doctrine ORM.

```bash
php Doctrine/Tests/ORM/Functional/Locking/LockAgentWorker.php
```

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

### Obtain EntityManager with XML metadata config

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/configuration.rst

Obtain an EntityManager instance using XML metadata configuration. Requires the same setup as the attribute example, but with XML mapping paths. On PHP < 8.4, use ORMSetup::createXMLMetadataConfiguration() instead.

```php
<?php
$paths = ['/path/to/xml-mappings'];
$config = ORMSetup::createXMLMetadataConfig($paths, $isDevMode);
// on PHP < 8.4, use ORMSetup::createXMLMetadataConfiguration() instead
$connection = DriverManager::getConnection($dbParams, $config);
$entityManager = new EntityManager($connection, $config);
```

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

### Table attribute example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Example of using #[Table] to specify the table name and schema for an entity. If not specified, the table name defaults to the unqualified class name.

```php
<?php
    use Doctrine\ORM\Mapping\Entity;
    use Doctrine\ORM\Mapping\Table;

    #[Entity]
    #[Table(name: "user", schema: "schema_name")]
    class User { }
```

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

### Before: NamingStrategy::joinColumnName() implementation

Source: https://github.com/doctrine/orm/blob/3.7.x/UPGRADE.md

Shows the previous signature of joinColumnName() with only a $propertyName parameter. This is the 'Before' example for the BC break introducing a new argument.

```php
<?php
class MyStrategy implements NamingStrategy
{
    /**
     * @param string $propertyName A property name.
     */
    public function joinColumnName($propertyName): string
    {
        // …
    }
}
```

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

### ManyToOne attribute example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Shows how to use #[ManyToOne] with a target entity, cascade option, and fetch mode.

```php
<?php
use Doctrine\ORM\Mapping\ManyToOne;

#[ManyToOne(targetEntity: "Cart", cascade: ["all"], fetch: "EAGER")]
private $cart;
```

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

### Low Level API: Using add() with Strings

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Shows how to build a DQL query using the low-level add() method with string parts. The example builds a SELECT query with a WHERE and ORDER BY clause.

```php
<?php
// $qb instanceof QueryBuilder

// example6: how to define:
// "SELECT u FROM User u WHERE u.id = ? ORDER BY u.name ASC"
// using QueryBuilder string support
$qb->add('select', 'u')
   ->add('from', 'User u')
   ->add('where', 'u.id = ?1')
   ->add('orderBy', 'u.name ASC');
```

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

### onFlush listener example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Example of an onFlush event listener. Called inside EntityManager::flush() after changes are computed. Provides access to scheduled entity and collection changes via UnitOfWork. Requires familiarity with UnitOfWork API.

```php
<?php
class FlushExampleListener
{
    public function onFlush(OnFlushEventArgs $eventArgs)
    {
        $em = $eventArgs->getObjectManager();
        $uow = $em->getUnitOfWork();

        foreach ($uow->getScheduledEntityInsertions() as $entity) {

        }

        foreach ($uow->getScheduledEntityUpdates() as $entity) {

        }

        foreach ($uow->getScheduledEntityDeletions() as $entity) {

        }

        foreach ($uow->getScheduledCollectionDeletions() as $col) {

        }

        foreach ($uow->getScheduledCollectionUpdates() as $col) {

        }
    }
}
```

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

### preUpdate listener example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Example of a preUpdate event listener. Called before an SQL UPDATE statement. Provides access to the computed changeset via PreUpdateEventArgs. Changing associations is not allowed. Use setNewValue to modify field values.

```php
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

class NeverAliceOnlyBobListener
{
    public function preUpdate(PreUpdateEventArgs $eventArgs)
    {
        if ($eventArgs->getEntity() instanceof User) {
            if ($eventArgs->hasChangedField('name') && $eventArgs->getNewValue('name') == 'Alice') {
                $eventArgs->setNewValue('name', 'Bob');
                // The following will only work if `status` is already present in the computed changeset.
                // Otherwise it will throw an InvalidArgumentException:
                $eventArgs->setNewValue('status', 'active');
            }
        }
    }
}
```

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

### Bootstrap Doctrine EntityManager

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Initializes the EntityManager using Doctrine DBAL and ORM setup. Requires vendor/autoload.php.

```php
<?php
// bootstrap.php
use Doctrine\DBAL\DriverManager;
use Doctrine\ORM\EntityManager;
use Doctrine\ORM\ORMSetup;

require_once "vendor/autoload.php";
```

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

### Create a new Bug entity (create_bug.php)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Starts the create_bug.php script, which expects three arguments: reporter ID, engineer ID, and a comma-separated list of product IDs. It requires bootstrap.php and parses the product IDs into an array.

```php
<?php
// create_bug.php <reporter-id> <engineer-id> <product-ids>
require_once "bootstrap.php";

$reporterId = $argv[1];
$engineerId = $argv[2];
$productIds = explode(",", $argv[3]);
```

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

### Lifecycle event subscriber example (postUpdate)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Shows a PHP class implementing an EventSubscriber for the postUpdate event. The subscriber returns the subscribed events from getSubscribedEvents() and handles the event in a method named after the event.

```php
<?php
use Doctrine\ORM\Event\PostUpdateEventArgs;
use Doctrine\ORM\Events;
use Doctrine\EventSubscriber;

class MyEventSubscriber implements EventSubscriber
{
    public function getSubscribedEvents()
    {
        return array(
            Events::postUpdate,
        );
    }

    public function postUpdate(PostUpdateEventArgs $args)
    {
        $entity = $args->getObject();
        $entityManager = $args->getObjectManager();

        // perhaps you only want to act on some "Product" entity
        if ($entity instanceof Product) {
            // do something with the Product
        }
    }
```

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

### Debugging DQL and SQL queries

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/faq.rst

Shows how to get the SQL from a DQL query and the DQL from a QueryBuilder. Useful for debugging query failures.

```php
<?php
$dql = "SELECT u FROM User u";
$query = $entityManager->createQuery($dql);
var_dump($query->getSQL());

$qb = $entityManager->createQueryBuilder();
$qb->select('u')->from('User', 'u');
var_dump($qb->getDQL());
```

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

### SequenceGenerator attribute example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Example of using #[SequenceGenerator] with #[GeneratedValue(strategy: "SEQUENCE")] to specify sequence details. Required parameter is sequenceName; optional are allocationSize (default 10) and initialValue (default 1).

```php
<?php
    use Doctrine\ORM\Mapping\Id;
    use Doctrine\ORM\Mapping\GeneratedValue;
    use Doctrine\ORM\Mapping\Column;
    use Doctrine\ORM\Mapping\SequenceGenerator;

    #[Id]
    #[GeneratedValue(strategy: "SEQUENCE")]
    #[Column(type: "integer")]
    #[SequenceGenerator(sequenceName: "tablename_seq", initialValue: 1, allocationSize: 100)]
    protected $id = null;
```

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

### Example XML mapping document for User entity

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/xml-mapping.rst

A complete example of an XML mapping document for an entity named Doctrine\Tests\ORM\Mapping\User with table cms_users. It includes indexes, unique constraints, and lifecycle callbacks.

```xml
// Doctrine.Tests.ORM.Mapping.User.dcm.xml
<?xml version="1.0" encoding="UTF-8"?>
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                          https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">

    <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">

        <indexes>
            <index name="name_idx" columns="name"/>
        </indexes>

        <unique-constraints>
            <unique-constraint columns="name,user_email" name="search_idx" />
        </unique-constraints>

        <lifecycle-callbacks>
            <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
            <lifecycle-callback type="prePersist" method="doOtherStuffOnPrePersistToo"/>
            <lifecycle-callback type="postPersist" method="doStuffOnPostPersist"/>
        </lifecycle-callbacks>

```

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

### Inheritance strategies with #[InheritanceType]

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Two examples of inheritance strategies: SINGLE_TABLE and JOINED. Both must be used with #[DiscriminatorMap] and #[DiscriminatorColumn] on the topmost/super class.

```php
<?php
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\InheritanceType;
use Doctrine\ORM\Mapping\DiscriminatorColumn;
use Doctrine\ORM\Mapping\DiscriminatorMap;

#[Entity]
#[InheritanceType("SINGLE_TABLE")]
#[DiscriminatorColumn(name: "discr", type: "string")]
#[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
class Person
{
    // ...
}
```

```php
<?php
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\InheritanceType;
use Doctrine\ORM\Mapping\DiscriminatorColumn;
use Doctrine\ORM\Mapping\DiscriminatorMap;

#[Entity]
#[InheritanceType("JOINED")]
#[DiscriminatorColumn(name: "discr", type: "string")]
#[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
class Person
{
    // ...
}
```

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

### Before: Implementing NamingStrategy::joinColumnName() with one argument

Source: https://github.com/doctrine/orm/blob/3.7.x/UPGRADE.md

Deprecated implementation of joinColumnName() with only one argument. This is the 'before' example for the deprecation of omitting the second argument.

```php
<?php
class MyStrategy implements NamingStrategy
{
    /**
     * @param string $propertyName A property name.
     */
    public function joinColumnName($propertyName): string
    {
        // …
    }
}

```

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

### Create a Bug with relations and run the script

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Creates a Bug entity, associates it with a reporter, engineer, and products, then persists it. The command line invocation passes the IDs of the reporter, engineer, and product (all 1 in this example).

```php
$reporter = $entityManager->find("User", $reporterId);
$engineer = $entityManager->find("User", $engineerId);
if (!$reporter || !$engineer) {
    echo "No reporter and/or engineer found for the given id(s).\n";
    exit(1);
}

$bug = new Bug();
$bug->setDescription("Something does not work!");
$bug->setCreated(new DateTime("now"));
$bug->setStatus("OPEN");

foreach ($productIds as $productId) {
    $product = $entityManager->find("Product", $productId);
    $bug->assignToProduct($product);
}

$bug->setReporter($reporter);
$bug->setEngineer($engineer);

$entityManager->persist($bug);
$entityManager->flush();

echo "Your new Bug Id: ".$bug->getId()."\n";
```

```bash
php create_bug.php 1 1 1
```

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

### Lifecycle event listener example (preUpdate)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Shows a PHP class implementing a lifecycle event listener for the preUpdate event. The listener receives PreUpdateEventArgs, accesses the entity and entity manager, and can check the entity type before acting.

```php
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

class MyEventListener
{
    public function preUpdate(PreUpdateEventArgs $args)
    {
        $entity = $args->getObject();
        $entityManager = $args->getObjectManager();

        // perhaps you only want to act on some "Product" entity
        if ($entity instanceof Product) {
            // do something with the Product
        }
    }
}
```

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

### AnnotationReader setup for Doctrine 2.1

Source: https://github.com/doctrine/orm/blob/3.7.x/UPGRADE.md

New setup for AnnotationReader after refactoring. Must register the Doctrine annotations file and configure the reader with setIgnoreNotImportedAnnotations(true) and setEnableParsePhpImports(false). This is already done inside newDefaultAnnotationDriver.

```php
\Doctrine\Common\Annotations\AnnotationRegistry::registerFile('/doctrine-src/src/Mapping/Driver/DoctrineAnnotations.php');

$reader = new \Doctrine\Common\Annotations\AnnotationReader();
$reader->setDefaultAnnotationNamespace('Doctrine\ORM\Mapping\\');
// new code necessary starting here
$reader->setIgnoreNotImportedAnnotations(true);
$reader->setEnableParsePhpImports(false);
$reader = new \Doctrine\Common\Annotations\CachedReader(
    new \Doctrine\Common\Annotations\IndexedReader($reader), new ArrayCache()
);
```

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

### Removing references and flushing

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/working-with-associations.rst

Example showing how to remove references from an entity and flush to delete associated entities from the database.

```php
<?php

$contact = $em->find("Addressbook\Contact", $contactId);
$contact->newStandingData(new StandingData("Firstname", "Lastname", "Street"));
$contact->removeAddress(1);

$em->flush();
```

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

### Build query with Expr class

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Use the Expr class to programmatically build conditions, as shown in a query port example.

```php
<?php

use SortDirection;

// $qb instanceof QueryBuilder

// example8: QueryBuilder port of:
// "SELECT u FROM User u WHERE u.id = ? OR u.nickname LIKE ? ORDER BY u.name ASC" using Expr class
$qb->add('select', new Expr\Select(array('u')))
   ->add('from', new Expr\From('User', 'u'))
   ->add('where', $qb->expr()->orX(
       $qb->expr()->eq('u.id', '?1'),
       $qb->expr()->like('u.nickname', '?2')
   ))
   ->add('orderBy', new Expr\OrderBy('u.name', SortDirection::Ascending));
```

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

### List Bugs Using EntityRepository

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Example of using an EntityRepository to fetch recent bugs and display them. It requires a bootstrap file and an entity manager. The output shows bug descriptions, creation dates, reporter and engineer names, and product platforms.

```php
<?php
// list_bugs_repository.php
require_once "bootstrap.php";

$bugs = $entityManager->getRepository('Bug')->getRecentBugs();

foreach ($bugs as $bug) {
    echo $bug->getDescription()." - ".$bug->getCreated()->format('d.m.Y')."\n";
    echo "    Reported by: ".$bug->getReporter()->getName()."\n";
    echo "    Assigned to: ".$bug->getEngineer()->getName()."\n";
    foreach ($bug->getProducts() as $product) {
        echo "    Platform: ".$product->getName()."\n";
    }
    echo "\n";
}
```

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

### Count results with count()

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/working-with-objects.rst

Counts the number of users matching the given conditions. The example checks that no user with the nickname 'nonexistent' exists by comparing the count to zero.

```php
<?php
// Check there is no user with nickname
$availableNickname = 0 === $em->getRepository('MyProject\Domain\User')->count(['nickname' => 'nonexistent']);
```

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

### Create project directories

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Create the config/xml and src directories as shown.

```text
doctrine2-tutorial
|-- config
|   `-- xml
`-- src
```

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

### Entity listener class with naming convention

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Example of an entity listener class that uses the naming convention. The method 'preUpdate' is automatically called for the 'preUpdate' event.

```php
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

class UserListener
{
    public function preUpdate(User $user, PreUpdateEventArgs $event)
    {
        // Do something on pre update.
    }
}
```

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

### Result of INDEX BY query

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/dql-doctrine-query-language.rst

Example output array from the INDEX BY query, showing the nested structure indexed by user id and phonenumber id.

```php
array
  0 =>
    array
      1 =>
        object(stdClass)[299]
          public '__CLASS__' => string 'Doctrine\Tests\Models\CMS\CmsUser' (length=33)
          public 'id' => int 1
          ..
      'nameUpper' => string 'ROMANB' (length=6)
  1 =>
    array
      2 =>
        object(stdClass)[298]
          public '__CLASS__' => string 'Doctrine\Tests\Models\CMS\CmsUser' (length=33)
          public 'id' => int 2
          ...
      'nameUpper' => string 'JWAGE' (length=5)
```

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

### Binding a named parameter with setParameter (u.id = :identifier)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Alternative syntax using a named placeholder. The query builder uses `setParameter('identifier', 100)` to set the value for `:identifier`. Named placeholders start with a colon (`:`) followed by a string. This example is equivalent to the numeric placeholder example but uses a named parameter.

```php
    <?php

    use SortDirection;

    // $qb instanceof QueryBuilder

    $qb->select('u')
       ->from('User', 'u')
       ->where('u.id = :identifier')
       ->orderBy('u.name', SortDirection::Ascending)
       ->setParameter('identifier', 100); // Sets :identifier to 100, and thus we will fetch a user with u.id = 100
```

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

### Class Table Inheritance with JOINED type

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/dql-doctrine-query-language.rst

Shows the entity definition for Class Table Inheritance by changing the inheritance type from SINGLE_TABLE to JOINED. The rest of the entity setup is the same as the single table example.

```php
<?php

#[Entity]
#[InheritanceType('JOINED')]
#[DiscriminatorColumn(name: 'discr', type: 'string')]
#[DiscriminatorMap(['person' => 'Person', 'employee' => 'Employee'])]
class Person
{
    // ...
}
```

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

### Partial index with #[Index] and 'where' option

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Example of a partial index using the 'where' option in the 'options' parameter. The WHERE condition only takes effect on supported platforms.

```php
<?php
use Doctrine\ORM\Mapping\Index;

#[Index(name: "search_idx", columns: ["category"],
    options: [
        "where" => "((category IS NOT NULL))"
    ]
)]
class ECommerceProduct
{
}
```

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

### List Products Script (list_products.php)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Fetches all Product entities using the repository and prints each product's name. Demonstrates the getRepository() and findAll() methods.

```php
<?php
// list_products.php
require_once "bootstrap.php";

$productRepository = $entityManager->getRepository('Product');
$products = $productRepository->findAll();

foreach ($products as $product) {
    echo sprintf("-%s\n", $product->getName());
}
```

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

### #[Column] attribute usage examples

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Shows common configurations for the #[Column] attribute on entity properties, including type, length, unique, index, columnDefinition, precision/scale for decimals, and options with fixed/comment or unsigned/default.

```php
<?php
use Doctrine\ORM\Mapping\Column;

#[Column(type: "string", length: 32, unique: true, nullable: false)]
protected $username;

#[Column(type: "string", index: true)]
protected $firstName;

#[Column(type: "string", columnDefinition: "CHAR(2) NOT NULL")]
protected $country;

#[Column(type: "decimal", precision: 2, scale: 1)]
protected $height;

#[Column(type: "string", length: 2, options: [
    "fixed" => true,
    "comment" => "Initial letters of first and last name"
])]
protected $initials;

#[Column(
    type: "integer",
    name: "login_count",
    nullable: false,
    options: ["unsigned" => true, "default" => 0]
)]
protected $loginCount;
```

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

### Race condition example with two requests

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/cookbook/aggregate-fields.rst

Illustrates a race condition where two requests load the same Account and both add entries, leading to an inconsistent aggregate field balance.

```php
<?php

use Bank\Entities\Account;

// The Account $accId has a balance of 0 and a max credit limit of 200:
// request 1 account
$account1 = $em->find(Account::class, $accId);

// request 2 account
$account2 = $em->find(Account::class, $accId);

$account1->addEntry(-200);
$account2->addEntry(-200);

// now request 1 and 2 both flush the changes.
```

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

### Binding a numeric parameter with setParameter (u.id = ?1)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Shows the basic approach to binding a parameter using a numeric placeholder. The query builder uses `setParameter(1, 100)` to set the value for `?1`. Note that numeric placeholders start with `?` followed by a number, and mixing numeric and named placeholders is not allowed. This example uses `SortDirection::Ascending` for ordering.

```php
    <?php

    use SortDirection;

    // $qb instanceof QueryBuilder

    $qb->select('u')
       ->from('User', 'u')
       ->where('u.id = ?1')
       ->orderBy('u.name', SortDirection::Ascending)
       ->setParameter(1, 100); // Sets ?1 to 100, and thus we will fetch a user with u.id = 100
```

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

### Command-Line Invocation for create_product.php

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Shows how to run the create_product.php script from the command line with a product name argument.

```bash
$ php create_product.php ORM
$ php create_product.php DBAL
```

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

### Generate documentation with composer docs

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/README.md

Run this command in the project root to generate the documentation into the 'docs/output' subdirectory.

```bash
composer docs
```

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

### Create Product Script (create_product.php)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Creates a new Product entity, persists it, and flushes to insert into the database. Requires a name argument from the command line. Outputs the new product ID.

```php
<?php
// create_product.php <name>
require_once "bootstrap.php";

$newProductName = $argv[1];

$product = new Product();
$product->setName($newProductName);

$entityManager->persist($product);
$entityManager->flush();

echo "Created Product with ID " . $product->getId() . "\n";
```

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

### Build a query using helper methods

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Demonstrates the standard way to construct a DQL query with select, from, where, and orderBy methods.

```php
<?php

use SortDirection;

// $qb instanceof QueryBuilder

$qb->select('u')
   ->from('User', 'u')
   ->where('u.id = ?1')
   ->orderBy('u.name', SortDirection::Ascending);
```

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

### Binding Parameters to Placeholders

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Shows how to use createNamedParameter() to bind a value to a placeholder and use it directly in the query. The example builds a SELECT query with a WHERE clause using the named parameter.

```php
<?php
// $qb instanceof QueryBuilder

$qb->select('u')
    ->from('User', 'u')
    ->where('u.email = ' .  $qb->createNamedParameter($userInputEmail))
;
// SELECT u FROM User u WHERE email = :dcValue1
```

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

### XML mapping document outline with xmlns/xsi setup

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/xml-mapping.rst

Shows the root element and namespace declarations required for an XML mapping document. The schemaLocation points to the latest XSD. The ellipsis (...) indicates where mapping content goes.

```xml
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                          https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">

    ...

</doctrine-mapping>
```

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

### findBy with ordering, limit, and offset

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/working-with-objects.rst

Retrieves up to ten users aged 20, ordered by name ascending, starting from the first result. The second parameter is an array of orderings, the third is the limit, and the fourth is the offset.

```php
<?php
$tenUsers = $em->getRepository('MyProject\Domain\User')->findBy(array('age' => 20), array('name' => 'ASC'), 10, 0);
```

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

### Low Level API: Using add() with Expr\* Instances

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Shows the same query as example6 but using Expr\* classes instead of strings. Demonstrates using Expr\Select, Expr\From, Expr\Comparison, and Expr\OrderBy.

```php
<?php

use SortDirection;

// $qb instanceof QueryBuilder

// example7: how to define:
// "SELECT u FROM User u WHERE u.id = ? ORDER BY u.name ASC"
// using QueryBuilder using Expr\* instances
$qb->add('select', new Expr\Select(array('u')))
   ->add('from', new Expr\From('User', 'u'))
   ->add('where', new Expr\Comparison('u.id', '=', '?1'))
   ->add('orderBy', new Expr\OrderBy('u.name', SortDirection::Ascending));
```

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

### postFlush listener example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/events.rst

Example of a postFlush event listener. Called at the end of EntityManager::flush(). Do not call flush() inside this listener. This event is not a lifecycle callback.

```php
<?php
use Doctrine\ORM\Event\PostFlushEventArgs;

class PostFlushExampleListener
{
    public function postFlush(PostFlushEventArgs $args)
    {
        // ...
    }
}
```

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

### Define Doctrine ORM requirement in composer.json

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/configuration.rst

Add this requirement to your composer.json file to install Doctrine ORM via Composer. After defining it, run 'composer install' from the command line.

```json
{
    "require": {
        "doctrine/orm": "*"
    }
}
```

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

### JoinColumn attribute example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Shows how to use #[JoinColumn] with a OneToOne relationship, specifying the foreign key column name, referenced column, and a custom foreign key constraint name.

```php
<?php
use Doctrine\ORM\Mapping\OneToOne;
use Doctrine\ORM\Mapping\JoinColumn;

#[OneToOne(targetEntity: Customer::class)]
#[JoinColumn(name: "customer_id", referencedColumnName: "id", foreignKeyName: "fk_customer")]
private $customer;
```

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

### Show Product Script (show_product.php)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Fetches a product by ID using the EntityManager's find() method. Prints the product name or an error message if not found.

```php
<?php
// show_product.php <id>
require_once "bootstrap.php";

$id = $argv[1];
$product = $entityManager->find('Product', $id);

if ($product === null) {
    echo "No product found.\n";
    exit(1);
}

echo sprintf("-%s\n", $product->getName());
```

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

### UniqueConstraint attribute example

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/attributes-reference.rst

Example of using #[UniqueConstraint] to define a unique constraint on columns. Required parameters are fields or columns; optional are name and options (like 'where' for partial indexes).

```php
<?php
    use Doctrine\ORM\Mapping\Entity;
    use Doctrine\ORM\Mapping\UniqueConstraint;

    #[Entity]
    #[UniqueConstraint(name: "ean", columns: ["ean"])]
    class ECommerceProduct
    {
    }
```

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

### Set and Get Metadata Driver Implementation

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/advanced-configuration.rst

Sets or gets the metadata driver implementation used by Doctrine to acquire object-relational metadata for your classes. Available implementations include AttributeDriver, XmlDriver, and DriverChain.

```php
<?php
$config->setMetadataDriverImpl($driver);
$config->getMetadataDriverImpl();
```

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

### Set and Get Proxy Namespace

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/advanced-configuration.rst

Sets or gets the namespace to use for generated proxy classes. Required except when using native lazy objects with PHP 8.4. This setting will be removed in the future.

```php
<?php
$config->setProxyNamespace($namespace);
$config->getProxyNamespace();
```

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

### Build a query with dynamic conditions using expr()

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/query-builder.rst

Shows how to use expression methods like orX, eq, and like to build queries with dynamic conditions.

```php
<?php

use SortDirection;

// $qb instanceof QueryBuilder

$qb->select(array('u')) // string 'u' is converted to array internally
   ->from('User', 'u')
   ->where($qb->expr()->orX(
       $qb->expr()->eq('u.id', '?1'),
       $qb->expr()->like('u.nickname', '?2')
   ))
   ->orderBy('u.surname', SortDirection::Ascending);
```

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

### Set and Get Proxy Directory

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/advanced-configuration.rst

Sets or gets the directory where Doctrine generates proxy classes. Required except when using native lazy objects with PHP 8.4. This setting will be removed in the future.

```php
<?php
$config->setProxyDir($dir);
$config->getProxyDir();
```

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

### Configure ORM and create EntityManager

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Sets up Doctrine ORM with attribute metadata (or XML as commented alternative), connects to a SQLite database, and creates an EntityManager. Requires Composer autoloading and assumes a bootstrap file.

```php
// Create a simple "default" Doctrine ORM configuration for Attributes
$config = ORMSetup::createAttributeMetadataConfig( // on PHP < 8.4, use ORMSetup::createAttributeMetadataConfiguration()
    paths: [__DIR__ . '/src'],
    isDevMode: true,
);
// or if you prefer XML
// $config = ORMSetup::createXMLMetadataConfig( // on PHP < 8.4, use ORMSetup::createXMLMetadataConfiguration()
//    paths: [__DIR__ . '/config/xml'],
//    isDevMode: true,
//);

// configuring the database connection
$connection = DriverManager::getConnection([
    'driver' => 'pdo_sqlite',
    'path' => __DIR__ . '/db.sqlite',
], $config);

// obtaining the entity manager
$entityManager = new EntityManager($connection, $config);
```

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

### CursorPage::getCursorForItem

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/pagination.rst

Builds a Cursor pointing at a specific entity. $isNext = true means "start after this item"; false means "start before this item".

```APIDOC
## CursorPage::getCursorForItem

### Description
Builds a Cursor pointing at a specific entity. $isNext = true means "start after this item"; false means "start before this item".

### Method
getCursorForItem

### Signature
CursorPage::getCursorForItem(mixed $item, bool $isNext = true): Cursor

### Parameters
- **$item** (mixed) - Required - The entity to build a cursor for.
- **$isNext** (bool) - Optional - Whether the cursor should start after (true) or before (false) the item. Defaults to true.

### Return Value
- **Cursor** - The cursor pointing at the specified entity.
```

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

### Count Products with Repository count()

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Counts products matching a given name using the repository's count() method. The method accepts an array of fields or association keys and values to match against.

```php
<?php
$productCount = $entityManager->getRepository(Product::class)
                         ->count(['name' => $productName]);
```

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

### Set and Get Metadata Cache

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/advanced-configuration.rst

Sets or gets the cache adapter for caching metadata information. The cache implementation must implement the PSR-6 Psr\Cache\CacheItemPoolInterface interface. Usage is highly recommended; for development, use an array cache like Symfony\Component\Cache\Adapter\ArrayAdapter.

```php
<?php
$config->setMetadataCache($cache);
$config->getMetadataCache();
```

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

### Basic entity cache usage

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/second-level-cache.rst

Demonstrates the basic usage of the second level cache: persisting and flushing an entity, clearing the entity manager, retrieving from cache, updating, and flushing again.

```php
<?php
$em->persist(new Country($name));
$em->flush();                         // Hit database to insert the row and put into cache

$em->clear();                         // Clear entity manager

$country1  = $em->find('Country', 1); // Retrieve item from cache

$country1->setName('New Name');

$em->flush();                         // Hit database to update the row and update cache

$em->clear();                         // Clear entity manager
```

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

### Mapped Superclass Example - PHP

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/reference/inheritance-mapping.rst

Defines a mapped superclass 'Person' with mapped fields and a one-to-one association, along with two entity subclasses 'Employee' and 'Toothbrush'. No database table is created for the mapped superclass itself. This example is used to illustrate how a mapped superclass can be used with unidirectional OneToOne associations.

```php
<?php
use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\JoinColumn;
use Doctrine\ORM\Mapping\OneToOne;
use Doctrine\ORM\Mapping\Id;
use Doctrine\ORM\Mapping\MappedSuperclass;
use Doctrine\ORM\Mapping\Entity;

#[MappedSuperclass]
class Person
{
    #[Column(type: 'integer')]
    protected int $mapped1;
    #[Column(type: 'string')]
    protected string $mapped2;
    #[OneToOne(targetEntity: Toothbrush::class)]
    #[JoinColumn(name: 'toothbrush_id', referencedColumnName: 'id')]
    protected Toothbrush|null $toothbrush = null;

    // ... more fields and methods
}

#[Entity]
class Employee extends Person
{
    #[Id, Column(type: 'integer')]
    private int|null $id = null;
    #[Column(type: 'string')]
    private string $name;

    // ... more fields and methods
}

#[Entity]
class Toothbrush
{
    #[Id, Column(type: 'integer')]
    private int|null $id = null;

    // ... more fields and methods
}

```

```sql
CREATE TABLE Employee (mapped1 INTEGER NOT NULL, mapped2 TEXT NOT NULL, id INTEGER NOT NULL, name TEXT NOT NULL, toothbrush_id INTEGER DEFAULT NULL, PRIMARY KEY(id))
```

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

### Create a new User entity (create_user.php)

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Creates a new User entity from a command-line argument. It requires a bootstrap.php file and expects the username as the first argument. After persisting and flushing, it prints the new user's ID.

```php
<?php
// create_user.php
require_once "bootstrap.php";

$newUsername = $argv[1];

$user = new User();
$user->setName($newUsername);

$entityManager->persist($user);
$entityManager->flush();

echo "Created User with ID " . $user->getId() . "\n";
```

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

### Run create_user.php with username

Source: https://github.com/doctrine/orm/blob/3.7.x/docs/en/tutorials/getting-started.rst

Runs the create_user.php script with the username 'beberlei' as the argument.

```bash
$ php create_user.php beberlei
```
Tokens:
Raw