Getting Started

Minimal Setup

Installation Add the bundle via Composer:

composer require doctrine/mongodb-odm-bundle

Enable it in config/bundles.php:

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

Configuration Define your MongoDB connection in config/packages/doctrine_mongodb.yaml:

doctrine_mongodb:
    connections:
        default:
            uri: '%env(MONGODB_URI)%'
            options: {}
    document_managers:
        default:
            connection: default
            mappings:
                App:
                    type: attribute
                    dir: '%kernel.project_dir%/src/Document'
                    prefix: 'App\Document'
                    alias: App

First Document Model Create a document class with the #[Document] attribute:

// src/Document/User.php
namespace App\Document;

use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;

#[ODM\Document(collection: "users")]
class User
{
    #[ODM\Id]
    private ?string $id = null;

    #[ODM\Field(type: "string")]
    private string $name;

    // Getters/setters...
}

First Query Use the DocumentManager in a service or controller:

use Doctrine\ODM\MongoDB\DocumentManager;

public function __construct(private DocumentManager $dm) {}

public function findUser(string $id): ?User
{
    return $this->dm->find(User::class, $id);
}

Implementation Patterns

Common Workflows

1. CRUD Operations

Create:

$user = new User();
$user->setName('John Doe');
$this->dm->persist($user);
$this->dm->flush();

Read:

$user = $this->dm->find(User::class, $id);
$users = $this->dm->getRepository(User::class)->findAll();

Update:

$user->setName('Updated Name');
$this->dm->flush();

Delete:

$this->dm->remove($user);
$this->dm->flush();

2. Querying with Criteria

Use Criteria for complex queries:

use Doctrine\ODM\MongoDB\Query\Criteria;

$criteria = Criteria::create()
    ->where(Criteria::expr()->eq('name', 'John Doe'))
    ->limit(10);

$query = $this->dm->createQueryBuilder(User::class)
    ->field('name')->equals('John Doe')
    ->hydrate(false)
    ->getQuery();

$results = $query->execute();

3. Repositories

Extend DocumentRepository for custom logic:

namespace App\Repository;

use App\Document\User;
use Doctrine\ODM\MongoDB\Repository\DocumentRepository;

class UserRepository extends DocumentRepository
{
    public function findByName(string $name): array
    {
        return $this->createQueryBuilder(User::class)
            ->field('name')->equals($name)
            ->getQuery()
            ->execute();
    }
}

4. Transactions

Use Transaction for atomic operations:

$this->dm->beginTransaction();
try {
    // Operations...
    $this->dm->commit();
} catch (\Exception $e) {
    $this->dm->rollback();
    throw $e;
}

5. Embedded Documents

Define relationships with #[EmbeddedDocument]:

#[ODM\EmbeddedDocument]
class Address
{
    #[ODM\Field(type: "string")]
    private string $street;
    // ...
}

#[ODM\Document]
class User
{
    #[ODM\EmbeddedOne(targetDocument: Address::class)]
    private Address $address;
}

6. References (Relationships)

Use #[ReferenceOne] or #[ReferenceMany]:

#[ODM\Document]
class Post
{
    #[ODM\ReferenceOne(targetDocument: User::class)]
    private ?User $author = null;
}

7. Lifecycle Callbacks

Use annotations like #[ODM\PrePersist]:

#[ODM\Document]
class User
{
    #[ODM\PrePersist]
    public function prePersist(): void
    {
        $this->createdAt = new \DateTime();
    }
}

8. Fixtures

Load test data with doctrine:mongodb:fixtures:load:

# config/packages/doctrine_mongodb.yaml
doctrine_mongodb:
    document_managers:
        default:
            fixtures:
                paths:
                    - '%kernel.project_dir%/src/DataFixtures/MongoDB'

// src/DataFixtures/MongoDB/UserFixture.php
namespace App\DataFixtures\MongoDB;

use App\Document\User;
use Doctrine\Bundle\MongoDBBundle\Fixture\FixtureInterface;
use Doctrine\Bundle\MongoDBBundle\Fixture\ServiceContainerAwareFixtureInterface;
use Doctrine\ODM\MongoDB\DocumentManager;
use Symfony\Component\DependencyInjection\ContainerAwareInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;

class UserFixture implements FixtureInterface, ServiceContainerAwareFixtureInterface, ContainerAwareInterface
{
    private DocumentManager $dm;
    private ContainerInterface $container;

    public function setContainer(ContainerInterface $container = null): void
    {
        $this->container = $container;
    }

    public function load(ObjectManager $dm): void
    {
        $this->dm = $dm;
        $user = new User();
        $user->setName('Fixture User');
        $dm->persist($user);
        $dm->flush();
    }
}

Integration Tips

1. Symfony Forms

Use MongoDBObject for form fields:

use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options): void
{
    $builder
        ->add('name', TextType::class);
}

2. API Platform

Annotate documents with #[ApiResource]:

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;

#[ApiResource]
#[ODM\Document]
class User
{
    // ...
}

3. Event Listeners

Subscribe to ODM events:

use Doctrine\ODM\MongoDB\Event\LifecycleEventArgs;

public function prePersist(LifecycleEventArgs $args): void
{
    $document = $args->getDocument();
    if ($document instanceof User) {
        $document->setUpdatedAt(new \DateTime());
    }
}

4. Custom Hydrators

Use Hydrator for custom serialization:

use Doctrine\ODM\MongoDB\Hydrator\HydratorInterface;

class CustomHydrator implements HydratorInterface
{
    public function hydrate(array $data, $document): void
    {
        // Custom logic...
    }
}

5. MongoDB GridFS

Use GridFS for large files:

use Doctrine\ODM\MongoDB\GridFS\GridFS;

$gridFS = $this->dm->getGridFS();
$file = $gridFS->storeFile($fileContent, ['metadata' => ['user_id' => $user->getId()]]);

Gotchas and Tips

Pitfalls

1. Schema Validation

MongoDB ODM does not enforce schema validation by default. Use strict: true in mappings for validation:

doctrine_mongodb:
    document_managers:
        default:
            mappings:
                App:
                    type: attribute
                    dir: '%kernel.project_dir%/src/Document'
                    prefix: 'App\Document'
                    strict: true  # Enforce schema validation

2. Lazy Loading

Enable native lazy loading (default in v5.5+):

doctrine_mongodb:
    document_managers:
        default:
            lazy_ghost_objects: true  # Default in v5.5+

Disable if needed:
```
lazy_ghost_objects: false
```

3. Id Generation

MongoDB uses _id by default

Mongodb Odm Bundle Laravel Package