README

TTTPTD Laravel Doctrine ODM

Laravel package for integrating Doctrine MongoDB ODM with Laravel applications.

This package started as a fork of chefsplate/laravel-doctrine-odm. The original project has not been maintained for a long time, so the fork was adapted for current Laravel applications and used privately in production projects for about a year and a half before being published. It is now public to make that work reusable, but the API and documentation are still being shaped around real project usage.

Table of Contents

• Background
• What It Solves
• Requirements
• Installation
• Configuration
• Document Path Registry
• Usage
• Artisan Commands
• Testing
• Local Package Development

Background

This package is based on chefsplate/laravel-doctrine-odm. Since the upstream package appeared to be abandoned and no longer tracked modern Laravel and Doctrine ODM versions, this fork evolved as a private, project-driven continuation. It has been used in real applications for roughly eighteen months before this public release.

What It Solves

Laravel does not include first-party Doctrine MongoDB ODM integration. This package provides the Laravel bridge:

• registers Doctrine DocumentManager in the Laravel container;
• publishes a MongoDB ODM config file;
• configures attribute metadata mapping;
• configures Doctrine proxies and hydrators;
• registers Gedmo Timestampable and Sluggable listeners;
• exposes Doctrine ODM console commands through Artisan;
• provides a small PersistenceManager abstraction for application code.

The package registers DocumentManager and PersistenceManager as scoped services. This is intentional: Doctrine DocumentManager is stateful and keeps an identity map/unit of work. In Laravel requests and queue jobs, one manager per lifecycle is the correct boundary; a singleton would leak stale documents between queue jobs.

Requirements

• PHP 8.2+
• Laravel 12
• MongoDB PHP extension
• MongoDB server

Install the MongoDB extension before installing the package:

pecl install mongodb

Then enable it in your PHP configuration if your environment does not do that automatically.

Installation

Install the package from Packagist:

composer require tttptd/laravel-doctrine-odm:^0.1.1

Laravel package discovery registers the service provider automatically:

Ys\LaravelOdm\DoctrineMongoDBServiceProvider::class

Publish the config:

php artisan vendor:publish --provider="Ys\LaravelOdm\DoctrineMongoDBServiceProvider"

This creates:

config/mongodb.php

Configuration

Minimal .env example:

DB_MONGO_SERVER=mongodb://localhost:27017
DB_MONGO_DATABASE=app

DOCTRINE_METADATA_CACHE=array
DOCTRINE_PROXY_AUTOGENERATE=2

Default document path:

'documents' => [
    base_path('app/Documents'),
],

For modular applications, configure all document roots explicitly:

'documents' => [
    base_path('app/Documents'),
    base_path('domain/Art'),
    base_path('domain/Commerce'),
],

If some directories must be skipped by the metadata driver, add exclude_documents:

'exclude_documents' => [
    base_path('domain/Art/tests'),
],

Proxy and hydrator files are generated into:

'proxies' => [
    'namespace' => 'Proxies',
    'path' => storage_path('mongo_proxies'),
],

'hydrators' => [
    'namespace' => 'Hydrators',
    'path' => storage_path('mongo_hydrators'),
],

For production, disable automatic proxy generation and generate proxies during deploy:

DOCTRINE_PROXY_AUTOGENERATE=2

2 means Configuration::AUTOGENERATE_FILE_NOT_EXISTS. The package also supports 3, Configuration::AUTOGENERATE_EVAL, which is useful only for development.

Document Path Registry

Ys\LaravelOdm\ODM\DocumentPathRegistry is the public extension point for ODM document paths owned by Laravel packages.

The host config/mongodb.php should describe only host-owned documents:

'documents' => [
    base_path('app/Documents'),
    base_path('bbs'),
],

Reusable packages should not require the host application to hardcode vendor/<package>/... paths. Instead, a package service provider can add its document root through the registry:

use Ys\LaravelOdm\ODM\DocumentPathRegistry;

$this->callAfterResolving(
    DocumentPathRegistry::class,
    static fn(DocumentPathRegistry $registry) =>
        $registry->addDocumentPath(__DIR__ . '/../Domain/Entities'),
);

The registry is seeded from mongodb.paths.documents and mongodb.paths.exclude_documents first. Package providers append their own paths afterwards, so the metadata driver receives:

host config paths + package registered paths

config/mongodb.php does not overwrite package paths because it is only the initial source used to create the registry. The final Doctrine AttributeDriver is built from the registry after Laravel package providers have had a chance to register additional paths.

Usage

Inject Doctrine DocumentManager directly when you need full ODM APIs:

use Doctrine\ODM\MongoDB\DocumentManager;

final readonly class CreateArticleHandler
{
    public function __construct(
        private DocumentManager $documentManager,
    ) {
    }

    public function handle(Article $article): void
    {
        $this->documentManager->persist($article);
        $this->documentManager->flush();
    }
}

Or inject the package abstraction when application code only needs persistence operations:

use Ys\LaravelOdm\ODM\PersistenceManager;

final readonly class CreateArticleHandler
{
    public function __construct(
        private PersistenceManager $persistenceManager,
    ) {
    }

    public function handle(Article $article): void
    {
        $this->persistenceManager->persist($article);
        $this->persistenceManager->flush();
    }
}

Example document:

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

#[ODM\Document(collection: 'articles')]
final class Article
{
    #[ODM\Id]
    private ?string $id = null;

    #[ODM\Field(type: 'string')]
    private string $title;
}

Artisan Commands

The package wraps common Doctrine ODM console commands as Artisan commands:

php artisan odm:generate:proxies
php artisan odm:generate:hydrators
php artisan odm:query
php artisan odm:clear-cache:metadata
php artisan odm:schema:create
php artisan odm:schema:drop
php artisan odm:schema:update
php artisan odm:schema:shard

Run Artisan list in your application to see the exact command signatures:

php artisan list odm

Testing

Install development dependencies:

composer install

Run the test suite:

composer test

The package uses PHPUnit 11 and Orchestra Testbench. The current tests cover:

• Laravel service provider registration;
• config publishing path;
• DocumentManagerFactory singleton lifetime;
• scoped DocumentManager lifecycle;
• PersistenceManager binding to the current scoped DocumentManager;
• Doctrine metadata loading from configured document paths;
• cache adapter creation;
• PersistenceManagerDoctrine delegation to Doctrine ODM.

The integration tests do not require a running MongoDB server. They verify container/config/metadata behavior without opening a database connection.

Local Package Development

For active development inside a Laravel application, clone this package next to the application:

~/example/laravel-doctrine-odm

In the application composer.json, temporarily add a path repository before installing/updating the package:

{
  "repositories": [
    {
      "type": "path",
      "url": "/Users/user/example/laravel-doctrine-odm",
      "options": {
        "symlink": true
      }
    }
  ]
}

Then update only this dependency:

composer update tttptd/laravel-doctrine-odm -W

With symlink: true, changes in the package checkout are immediately visible in the Laravel application.

Before committing application changes meant for CI/production, make sure composer.lock does not lock the package to a local path repository unless that is intentional. Public projects should normally resolve this package from Packagist.