README

A resilient MongoDB client built on the official mongodb/mongodb library and ext-mongodb. It adds fluent CRUD builders, a Document object over raw BSON, a typed exception hierarchy translated from driver errors, optional query logging, and a connector so phpdot/pool can hold and recycle connections.

Requirements
Installation
Usage
Architecture
Testing
License

Requirements

Requirement	Constraint
PHP	`>= 8.5`
`ext-mongodb`	`^2.1`
`mongodb/mongodb`	`^2.1`
`phpdot/contracts`	`^0.1`

phpdot/container is a dev-only suggestion — the #[Config('mongodb')] attribute on MongoConfig is inert until a phpdot application reflects it.

Installation

composer require phpdot/mongodb

Usage

Connecting and CRUD

use PHPdot\MongoDB\MongoConnection;
use PHPdot\MongoDB\Config\MongoConfig;
use PHPdot\MongoDB\Database\Database;

$connection = new MongoConnection(new MongoConfig(
    hosts: 'localhost',
    database: 'myapp',
));
$connection->connect();

$users = (new Database($connection))->collection('users');

$users->insertOne(['name' => 'Omar', 'email' => 'omar@example.com']);

$user = $users->findOne(['email' => 'omar@example.com']);
echo $user->name; // 'Omar' — a Document with field access

Fluent queries

Find, update, and delete each have a fluent builder:

$active = $users->find()
    ->filter(['status' => 'active'])
    ->sort(['created_at' => -1])
    ->limit(10)
    ->execute();

foreach ($active as $doc) {
    echo $doc->name;
}

$users->update()
    ->filter(['status' => 'pending'])
    ->set(['status' => 'active'])
    ->execute();

$users->delete()->filter(['status' => 'banned'])->execute();

Documents

findOne() and cursors yield Document objects — field access, dot-path reads, type conversions, and ArrayAccess/JsonSerializable, over the raw BSON the driver returns.

Resilience and exceptions

connect() retries with exponential backoff up to maxRetries. Driver errors are translated into a typed hierarchy — AuthenticationException, ConnectionException, TimeoutException, DuplicateKeyException, BulkWriteException, ValidationException, and more — all extending the package's MongoException.

Pooling

MongoConnector adapts a MongoConnection to phpdot/pool's ConnectorInterface, so a pool can build, health-check, and recycle connections — one connection per coroutine.

Architecture

MongoConnection owns a MongoDB\Client and drives its lifecycle (backoff connect, ping, exception translation). Database and Collection expose the fluent API; the query builders compile to the options the underlying library accepts. MongoConnector bridges to phpdot/pool.

graph TD
    APP["Application / phpdot/pool"]
    CONNECTOR["MongoConnector<br/><br/>Contracts Pool ConnectorInterface"]
    CONN["MongoConnection<br/><br/>lifecycle, backoff reconnect,<br/>exception translation, query log"]
    DB["Database → Collection<br/><br/>Find / Update / Delete builders,<br/>Document over BSON"]
    CONFIG["MongoConfig<br/><br/>hosts, topology, timeouts<br/>(#[Config('mongodb')])"]
    LIB["mongodb/mongodb + ext-mongodb<br/><br/>MongoDB\\Client, MongoDB\\Driver\\*"]

    APP --> CONNECTOR
    CONNECTOR --> CONN
    CONFIG --> CONN
    CONN --> DB
    DB --> LIB
    CONN --> LIB

Testing

composer install
composer test        # PHPUnit
composer analyse     # PHPStan, level max + strict rules
composer cs-check    # PHP-CS-Fixer
composer check       # All three

The unit suite runs with no server. The integration suite connects to a MongoDB at 127.0.0.1:27017 and skips automatically when none is reachable.

License

MIT.

This repository is a read-only mirror, generated by CI from phpdot/monorepo. Pull requests and issues belong in the monorepo.

phpdot / mongodb

Maintainers

Package info

Statistics

Security