PHP MongoDB — Silent Data Loss from Default Write Concern

Most PHP applications start life with MySQL — structured, reliable, familiar. But somewhere around the time your product manager asks for 'flexible user profiles', 'nested product attributes', or 'activity feeds that look different for every user type', a relational schema starts to feel like wearing shoes two sizes too small. You spend more time writing ALTER TABLE migrations and LEFT JOIN acrobatics than you spend actually building features. That's not a MySQL problem — it's a data-shape mismatch problem, and MongoDB was built to solve it at scale.

MongoDB stores data as BSON documents — Binary JSON objects that can nest arrays, sub-documents, and mixed types without a schema police officer stopping you at the door. PHP connects to it via the official mongodb/mongodb Composer package, which wraps the low-level ext-mongodb C extension. This split architecture (C extension for raw performance, PHP library for ergonomic developer experience) means you get near-native speed without writing a single line of C. The driver handles connection pooling, BSON serialisation, cursor streaming, and write concern negotiation transparently.

By the end of this article you'll know how to wire up PHP to MongoDB correctly in production, write efficient CRUD operations and aggregation pipelines, design indexes that don't destroy your write throughput, and dodge the six most painful production mistakes that nobody warns you about until your on-call phone rings at 2am.

What is PHP and MongoDB?

At its heart, PHP+MongoDB means using PHP to interact with a document-oriented NoSQL database. You store data as BSON documents — think JSON but with strongly-typed fields. The PHP driver handles the serialisation and deserialisation so you work with native PHP arrays or objects. This pairing shines when your data model changes frequently, when you need to embed related data directly, or when you need high write throughput. For example, a user profile with address history and preferences can be stored in a single document instead of normalising across three tables. That's not just convenience — it eliminates expensive joins and makes read operations 10x faster in many cases.

Here's how a basic query looks in PHP:

```php <?php namespace Io\TheCodeForge\MongoDb;

use MongoDB\Client;

$client = new Client(getenv('MONGODB_URI')); $collection = $client->selectDatabase('ecommerce')->selectCollection('products');

$product = $collection->findOne(['sku' => 'PHONE-001']); echo $product['name'] . ' - $' . $product['price']; ```

Notice you're working with arrays directly — no schema definition, no migration, no ORM configuration. That's the speed advantage that matters when your data shape changes weekly.

<?php
namespace Io\TheCodeForge\MongoDb;

use MongoDB\Client;

$client = new Client(getenv('MONGODB_URI'));
$collection = $client->selectDatabase('ecommerce')->selectCollection('products');

$product = $collection->findOne(['sku' => 'PHONE-001']);
echo $product['name'] . ' - $' . $product['price'];

Driver Installation and Connection Setup

Getting PHP to talk to MongoDB involves two components: the C extension (ext-mongodb) and the PHP library (mongodb/mongodb). Install both via PECL and Composer:

``bash pecl install mongodb echo "extension=mongodb.so" >> php.ini composer require mongodb/mongodb ``

Then create a connection manager. Never hardcode credentials — use environment variables.

```php <?php namespace Io\TheCodeForge\MongoDb;

use MongoDB\Client; use MongoDB\Driver\Manager;

class ConnectionManager { private static ?Client $client = null;

public static function getClient(): Client { if (self::$client === null) { $uri = getenv('MONGODB_URI') ?: 'mongodb://localhost:27017'; $uriOptions = [ 'readPreference' => 'secondaryPreferred', 'w' => 'majority', 'journal' => true, 'connectTimeoutMS' => 3000, 'socketTimeoutMS' => 10000 ]; $driverOptions = [ 'typeMap' => ['root' => 'array', 'document' => 'array', 'array' => 'array'], ]; self::$client = new Client($uri, $uriOptions, $driverOptions); } return self::$client; } } ```

The typeMap option converts BSON documents to PHP arrays instead of stdClass objects — faster and less error-prone. The readPreference lets read queries hit secondaries, offloading the primary.

One more thing: always set a reasonable connectTimeoutMS (like 3000ms) and socketTimeoutMS (like 10000ms) in your uriOptions. Without these, a MongoDB node that's slow to respond can hang your PHP process indefinitely. Trust me, you'll learn this the hard way when your FPM workers pile up waiting for a dead secondary.

<?php
namespace Io\TheCodeForge\MongoDb;

use MongoDB\Client;
use MongoDB\Driver\Manager;

class ConnectionManager
{
    private static ?Client $client = null;

    public static function getClient(): Client
    {
        if (self::$client === null) {
            $uri = getenv('MONGODB_URI') ?: 'mongodb://localhost:27017';
            $uriOptions = [
                'readPreference' => 'secondaryPreferred',
                'w' => 'majority',
                'journal' => true,
                'connectTimeoutMS' => 3000,
                'socketTimeoutMS' => 10000
            ];
            $driverOptions = [
                'typeMap' => ['root' => 'array', 'document' => 'array', 'array' => 'array'],
            ];
            self::$client = new Client($uri, $uriOptions, $driverOptions);
        }
        return self::$client;
    }
}

CRUD Operations with Documents

MongoDB documents are BSON objects with nested structures. PHP's mongodb/mongodb library maps PHP arrays to BSON automatically. But watch out for type conversions — timestamps, ObjectIds, and large integers are common traps.

Insert: Pass an array with keys. Use ['_id' => new MongoDB\BSON\ObjectId()] only if you need client-generated IDs. Otherwise let MongoDB handle it.

Find: The find() method returns a MongoDB\Collection object that iterates lazily. Use ->toArray() for small result sets, cursor iteration for large ones. Always pass projection to limit fields returned over the wire.

Update: Use updateOne() or updateMany() with atomic operators like $set, $unset, $inc. Never read-modify-write — that's a race condition in disguise.

Delete: deleteOne() and deleteMany() are final. Use them sparingly; mark documents as deleted: true instead for recoverability.

Example with error handling and bulk write:

```php <?php namespace Io\TheCodeForge\MongoDb;

use MongoDB\Collection; use MongoDB\Driver\Exception\RuntimeException;

class UserRepository { private Collection $collection;

public function __construct() { $this->collection = ConnectionManager::getClient() ->selectDatabase('myapp') ->selectCollection('users'); }

public function updateEmail(string $userId, string $newEmail): bool { try { $result = $this->collection->updateOne( ['_id' => new \MongoDB\BSON\ObjectId($userId)], ['$set' => ['email' => $newEmail]] ); return $result->getModifiedCount() === 1; } catch (RuntimeException $e) { error_log("MongoDB update failed: " . $e->getMessage()); return false; } }

public function batchUpdateStatus(array $userIds, string $status): int { $operations = []; foreach ($userIds as $id) { $operations[] = [ 'updateOne' => [ ['_id' => new \MongoDB\BSON\ObjectId($id)], ['$set' => ['status' => $status]] ] ]; } $result = $this->collection->bulkWrite($operations, ['ordered' => false]); return $result->getModifiedCount(); } } ```

bulkWrite with ordered => false runs operations in parallel — use it for batch jobs where order doesn't matter. For account transfers, keep ordered => true to maintain sequence.

One more thing: findOneAndUpdate is your atomic read-modify-write tool. It returns the updated document and guarantees no other process snuck in between. Perfect for counters, reservation systems, and queue pop operations.

<?php
namespace Io\TheCodeForge\MongoDb;

use MongoDB\Collection;
use MongoDB\Driver\Exception\RuntimeException;

class UserRepository
{
    private Collection $collection;

    public function __construct()
    {
        $this->collection = ConnectionManager::getClient()
            ->selectDatabase('myapp')
            ->selectCollection('users');
    }

    public function updateEmail(string $userId, string $newEmail): bool
    {
        try {
            $result = $this->collection->updateOne(
                ['_id' => new \MongoDB\BSON\ObjectId($userId)],
                ['$set' => ['email' => $newEmail]]
            );
            return $result->getModifiedCount() === 1;
        } catch (RuntimeException $e) {
            error_log("MongoDB update failed: " . $e->getMessage());
            return false;
        }
    }

    public function batchUpdateStatus(array $userIds, string $status): int
    {
        $operations = [];
        foreach ($userIds as $id) {
            $operations[] = [
                'updateOne' => [
                    ['_id' => new \MongoDB\BSON\ObjectId($id)],
                    ['$set' => ['status' => $status]]
                ]
            ];
        }
        $result = $this->collection->bulkWrite($operations, ['ordered' => false]);
        return $result->getModifiedCount();
    }
}

Aggregation Pipeline: Powerful Data Processing

MongoDB's aggregation pipeline processes documents through a sequence of stages: $match, $group, $sort, $project, $lookup, $unwind, etc. Each stage transforms the document stream, and the pipeline is executed in memory unless allowDiskUse is set.

Best practice: Place $match as early as possible. Use $project to drop unused fields. For expensive $lookup, consider denormalizing data if the foreign collection is mostly static.

Example: Aggregate orders by status with total value:

``php $pipeline = [ ['$match' => ['created_at' => ['$gte' => new \MongoDB\BSON\UTCDateTime($startOfDay)]]], ['$group' => [ '_id' => '$status', 'count' => ['$sum' => 1], 'totalValue' => ['$sum' => '$total_amount'] ]], ['$sort' => ['totalValue' => -1]] ]; $orders = $collection->aggregate($pipeline, ['allowDiskUse' => true, 'maxTimeMS' => 5000]); foreach ($orders as $order) { echo "{$order['_id']}: {$order['count']} orders, total \${$order['totalValue']} "; } ``

Note: allowDiskUse is necessary for large datasets — otherwise MongoDB may throw a 16819 error when memory limit is exceeded.

A common trap with $lookup is forgetting that the localField value is taken as-is, so if it's a string, the foreign field must also be a string — not an ObjectId. This mismatch causes silent empty results and hours of debugging. Always check types in the explain output.

<?php
namespace Io\TheCodeForge\MongoDb;

$collection = ConnectionManager::getClient()
    ->selectDatabase('ecommerce')
    ->selectCollection('orders');

$startOfDay = (new \DateTime('today midnight'))->getTimestamp() * 1000;

$pipeline = [
    ['$match' => ['created_at' => ['$gte' => new \MongoDB\BSON\UTCDateTime($startOfDay)]]],
    ['$group' => [
        '_id' => '$status',
        'count' => ['$sum' => 1],
        'totalValue' => ['$sum' => '$total_amount']
    ]],
    ['$sort' => ['totalValue' => -1]]
];
$orders = $collection->aggregate($pipeline, ['allowDiskUse' => true, 'maxTimeMS' => 5000]);
foreach ($orders as $order) {
    echo "{$order['_id']}: {$order['count']} orders, total \${$order['totalValue']}\n";
}

Indexing Strategy and Production Gotchas

Indexes in MongoDB are B-trees, similar to relational databases. But compound index prefix rules, query shape sensitivity, and the impact on write throughput differ.

Single field index: createIndex(['email' => 1]) — for exact matches or sort on email.

Compound index: createIndex(['status' => 1, 'created_at' => -1]) — supports queries on status, or status+created_at, but NOT on created_at alone.

Text index: createIndex(['description' => 'text']) — for full-text search with $text queries. Only one text index per collection.

Production pitfalls: 1. Too many indexes on a write-heavy collection -> each insert/update touches every index, doubling write time. 2. Unused indexes: use $indexStats to identify dead indexes. 3. Overusing hint() to force an index -> query optimizer disabled. 4. Not using dropIndexes() during migrations; building new indexes on large collections blocks read operations.

Use explain() before deploying any query to production:

``php $cursor = $collection->find( ['status' => 'active', 'created_at' => ['$gte' => $date]], ['projection' => ['_id' => 0, 'email' => 1]] ); $explain = $collection->find( ['status' => 'active', 'created_at' => ['$gte' => $date]], ['projection' => ['_id' => 0, 'email' => 1], 'explain' => true] ); ``

The explain output shows whether a COLLSCAN (collection scan) or IXSCAN (index scan) is used. Aim for IXSCAN with low totalDocsExamined relative to nReturned.

One more gotcha: MongoDB's query planner caches plans. If a suboptimal plan gets cached because of a skewed data distribution, you'll see slow queries even with the right indexes. Run db.collection.getPlanCache().clear() occasionally to force re-evaluation.

<?php
namespace Io\TheCodeForge\MongoDb;

use MongoDB\Collection;

$ordersCollection = ConnectionManager::getClient()
    ->selectDatabase('ecommerce')
    ->selectCollection('orders');

// Compound index for common query pattern
$ordersCollection->createIndex(
    ['status' => 1, 'created_at' => -1, 'customer_id' => 1],
    ['background' => true]
);

// Text index for product search
$productsCollection->createIndex(
    ['description' => 'text', 'name' => 'text'],
    ['default_language' => 'english']
);

// Monitor index usage
$indexStats = $ordersCollection->aggregate([['$indexStats' => []]]);
foreach ($indexStats as $stat) {
    echo "Index: " . $stat['name'] . " - accesses: " . $stat['accesses']['ops'] . "\n";
}

Transactions, Write Concerns, and Data Integrity

MongoDB supports multi-document ACID transactions since version 4.0. But they come with caveats: they only work on replica sets, have a 60-second default timeout, and should not be used for high-throughput operations that can be done with atomic operators.

Write concern controls durability. The default w: 1 acknowledges after primary memory write — not durable. w: majority waits for majority of replica set members. Adding j: true forces journal commit before acknowledgment.

Read concerns: local (default) returns data that may be rolled back. majority returns only committed data. Use linearizable only when you need absolute latest data, but it's slow.

Example transaction with retry logic:

```php <?php namespace Io\TheCodeForge\MongoDb;

$client = ConnectionManager::getClient(); $maxRetries = 3; $retry = 0;

do { $session = $client->startSession(); $session->startTransaction([ 'readConcern' => new \MongoDB\Driver\ReadConcern(\MongoDB\Driver\ReadConcern::SNAPSHOT), 'writeConcern' => new \MongoDB\Driver\WriteConcern(\MongoDB\Driver\WriteConcern::MAJORITY) ]); try { $accounts = $client->selectDatabase('bank')->selectCollection('accounts'); $accounts->updateOne( ['_id' => new \MongoDB\BSON\ObjectId($fromId)], ['$inc' => ['balance' => -100]], ['session' => $session] ); $accounts->updateOne( ['_id' => new \MongoDB\BSON\ObjectId($toId)], ['$inc' => ['balance' => 100]], ['session' => $session] ); $session->commitTransaction(); break; } catch (\MongoDB\Driver\Exception\CommandException $e) { $session->abortTransaction(); if ($e->hasErrorLabel('TransientTransactionError') && ++$retry < $maxRetries) { usleep(100000); // 100ms backoff continue; } throw $e; } } while (true); ```

Performance: transactions add 20-50ms overhead due to conflict detection. Use them sparingly.

If you're on MongoDB 4.2+, you can also use distributed transactions across sharded clusters. But the latency penalty is higher — expect 100-200ms per transaction. Only do this when the business requirement genuinely demands cross-shard atomicity.

<?php
namespace Io\TheCodeForge\MongoDb;

$client = ConnectionManager::getClient();
$session = $client->startSession();
$session->startTransaction([
    'readConcern' => new \MongoDB\Driver\ReadConcern(\MongoDB\Driver\ReadConcern::SNAPSHOT),
    'writeConcern' => new \MongoDB\Driver\WriteConcern(\MongoDB\Driver\WriteConcern::MAJORITY)
]);
try {
    $accounts = $client->selectDatabase('bank')->selectCollection('accounts');
    $accounts->updateOne(
        ['_id' => new \MongoDB\BSON\ObjectId($fromId)],
        ['$inc' => ['balance' => -100]],
        ['session' => $session]
    );
    $accounts->updateOne(
        ['_id' => new \MongoDB\BSON\ObjectId($toId)],
        ['$inc' => ['balance' => 100]],
        ['session' => $session]
    );
    $session->commitTransaction();
} catch (\Exception $e) {
    $session->abortTransaction();
    error_log('Transaction failed: ' . $e->getMessage());
}

Change Streams: Real-Time Data Feeds with PHP

MongoDB change streams allow you to subscribe to real-time changes on a collection, database, or entire deployment. They're built on the oplog and provide a reliable, ordered stream of events. In PHP, you use the MongoDB\Collection::watch() method to start listening.

Example: Watch for new orders with resume token persistence:

```php <?php namespace Io\TheCodeForge\MongoDb;

$orderCollection = ConnectionManager::getClient() ->selectDatabase('ecommerce') ->selectCollection('orders');

$resumeToken = $metadataCollection->findOne(['_id' => 'changeStreamResume'])['token'] ?? null; $options = ['maxAwaitTimeMS' => 1000]; if ($resumeToken) { $options['startAfter'] = $resumeToken; }

$pipeline = [['$match' => ['operationType' => 'insert']]]; $cursor = $orderCollection->watch($pipeline, $options);

foreach ($cursor as $event) { $order = $event['fullDocument']; // Send to a queue, update cache, etc. echo "New order: " . $order['_id'] . PHP_EOL; // Persist resume token $metadataCollection->updateOne( ['_id' => 'changeStreamResume'], ['$set' => ['token' => $event['_id']]], ['upsert' => true] ); } ```

Change streams don't work with transactions — you can't see uncommitted changes. That's fine, because you only want to react to committed data anyway.

<?php
namespace Io\TheCodeForge\MongoDb;

$orderCollection = ConnectionManager::getClient()
    ->selectDatabase('ecommerce')
    ->selectCollection('orders');

$pipeline = [['$match' => ['operationType' => 'insert']]];
$cursor = $orderCollection->watch($pipeline, ['maxAwaitTimeMS' => 1000]);

foreach ($cursor as $event) {
    $order = $event['fullDocument'];
    // Send to a queue, update cache, etc.
    echo "New order: " . $order['_id'] . PHP_EOL;
}

Replica Set Configuration and Failover Handling

A MongoDB replica set provides automatic failover and data redundancy. The PHP driver discovers replica set members from the connection string and routes writes to the primary. But proper configuration is critical — missteps can cause silent failover delays or split-brain scenarios.

Connection string: Use the SRV format for automatic discovery: mongodb+srv://user:pass@cluster0.example.mongodb.net/db?retryWrites=true&w=majority. This tells the driver to query DNS for all replica set members.

Read preference: Set to secondaryPreferred for read-heavy workloads, but be aware of stale reads. If you read-after-write, use primary or enable causal consistency.

Retry writes: Always enable retryWrites=true in the connection string. This re-runs write operations if the primary steps down during a write. It doesn't replace write concern, but adds resilience.

Failover test script:

```php <?php namespace Io\TheCodeForge\MongoDb;

$uri = 'mongodb+srv://user:pass@cluster0.example.mongodb.net/db?retryWrites=true&w=majority'; $client = new MongoDB\Client($uri);

$collection = $client->selectDatabase('test')->selectCollection('failover');

// Step down the primary (requires admin) $admin = $client->selectDatabase('admin'); $admin->command(['replSetStepDown' => 60, 'force' => true]);

// Try to write immediately — should retry automatically $collection->insertOne(['test' => 'failover', 'ts' => new MongoDB\BSON\UTCDateTime()]); echo "Write succeeded after failover. "; ```

Always test failover in a staging environment. Simulate primary step-down, network partitions, and secondary lag before going live.

<?php
namespace Io\TheCodeForge\MongoDb;

$uri = 'mongodb+srv://user:pass@cluster0.example.mongodb.net/db?retryWrites=true&w=majority';
$client = new MongoDB\Client($uri);

$collection = $client->selectDatabase('test')->selectCollection('failover');

// Step down the primary (requires admin)
$admin = $client->selectDatabase('admin');
$admin->command(['replSetStepDown' => 60, 'force' => true]);

// Try to write immediately — should retry automatically
$collection->insertOne(['test' => 'failover', 'ts' => new MongoDB\BSON\UTCDateTime()]);
echo "Write succeeded after failover.\n";

Handling Schema Migrations Without Downtime

You shipped MongoDB because you thought 'schemaless' meant you'd never touch migrations again. Wrong. Schemaless just means the database won't scream at you, but your application will silently corrupt data when you add a field that old documents don't have. Real downtime happens when a new code path expects a field that doesn't exist in production documents from six months ago.

The fix: write defensive read paths with $exists checks or use MongoDB's schema validation with $jsonSchema. But the real trick is incremental migrations. Never update all documents at once. Run a background script that iterates with a cursor noBatchSize and a write concern of acknowledged. Add the new field with a default, then update your application to read both old and new shapes. Only after you've confirmed zero read errors do you drop the fallback logic. This is how you avoid a 3 AM outage because your aggregation pipeline exploded on a null field that doesn't exit gracefully.

// io.thecodeforge — php tutorial

$collection = (new MongoDB\Client)->inventory->products;

// Step 1: Add new field with default to documents that lack it
$filter = ['warranty_years' => ['$exists' => false]];
$update = ['$set' => ['warranty_years' => 1]];
$options = ['batchSize' => 500, 'writeConcern' => new MongoDB\Driver\WriteConcern(1)];

$cursor = $collection->find($filter, $options);
foreach ($cursor as $doc) {
    $collection->updateOne(
        ['_id' => $doc['_id']],
        ['$set' => ['warranty_years' => 1]]
    );
    // Log progress for rollback tracking
    error_log('Migrated: ' . $doc['_id']);
}

// Output:
// Migrated: 66d8e2f4a1b2c3d4e5f6a7b8
// Migrated: 66d8e2f4a1b2c3d4e5f6a7b9
// ...
// (script logs each migrated document ID)

Time-Series Data: Writes That Won't Burn Your IO Budget

MongoDB time-series collections are not a magic bullet. They're a specialized tool that forces you to think about data granularity before you write a single line of PHP. The default approach—write one document per event per second—will destroy your write throughput and blow up your storage costs. Why? Because every write triggers an index update, and with millions of small documents, you're paying for metadata overhead.

The right move: bucket your data. MongoDB time-series collections do this automatically, but only if you define the metaField and granularity correctly. Set granularity to 'seconds' if you're logging IoT sensor data every tick. Use 'minutes' for aggregated metrics like API response times. If you don't, MongoDB will guess and likely get it wrong, forcing your queries to scan more buckets than necessary. Then you'll wonder why your $avg aggregation on the last hour takes eight seconds.

Here's the pattern: group your measurements by sensor_id as the metaField, then let MongoDB's internal bucketing compress writes. Your PHP code just inserts flat documents—MongoDB handles the compression. But remember: a poorly chosen granularity means your data stays uncompressed. Profiling your query patterns before picking granularity saves you a rewrite.

// io.thecodeforge — php tutorial

// Create time-series collection once
$db = (new MongoDB\Client)->iot_db;
$db->createCollection('sensor_readings', [
    'timeseries' => [
        'timeField' => 'timestamp',
        'metaField' => 'sensor_id',
        'granularity' => 'seconds'
    ]
]);

$collection = $db->sensor_readings;

// Insert raw events — MongoDB handles bucketing
$batch = [
    ['timestamp' => new MongoDB\BSON\UTCDateTime(), 'sensor_id' => 'sensor_alpha', 'temperature' => 72.3],
    ['timestamp' => new MongoDB\BSON\UTCDateTime(), 'sensor_id' => 'sensor_alpha', 'temperature' => 72.1],
    ['timestamp' => new MongoDB\BSON\UTCDateTime(), 'sensor_id' => 'sensor_beta', 'temperature' => 68.9]
];

$result = $collection->insertMany($batch);
echo 'Inserted ' . $result->getInsertedCount() . ' events';

// Output:
// Inserted 3 events

Bulletproof Error Handling: Don't Let a Dead MongoDB Takedown Your App

Production MongoDB goes down. Drivers throw exceptions. Network partitions happen. The difference between a senior dev and a junior is how gracefully you handle that moment. You catch, log, circuit-break, and retry — not bury errors in a try-catch with a generic 'something went wrong'.

MongoDB PHP driver throws MongoDB\Driver\Exception\ConnectionTimeoutException when it can't reach the server. Your code must treat this as a first-class failure path. Implement exponential backoff. Use a health-check loop before touching the database. Log the full error context including server host and operation.

Don't let a missing database bring down your entire page. Catch specific exceptions, present a stale cache, and alert ops. Your users forgive a stale dashboard. They don't forgive a 500 error.

// io.thecodeforge — php tutorial

function fetchUserOrders(string $userId, int $retries = 3): array {
    $attempt = 0;
    while ($attempt < $retries) {
        try {
            $collection = (new MongoDB\Client())->ecommerce->orders;
            return $collection->find(['user_id' => $userId])->toArray();
        } catch (MongoDB\Driver\Exception\ConnectionTimeoutException $e) {
            $attempt++;
            error_log("MongoDB timeout: {$e->getMessage()} (attempt {$attempt})");
            if ($attempt >= $retries) {
                throw $e;
            }
            usleep(100000 * pow(2, $attempt)); // exponential backoff: 200ms, 400ms, 800ms
        }
    }
    return [];
}

try {
    $orders = fetchUserOrders('abc123');
} catch (\Throwable $e) {
    http_response_code(503);
    echo json_encode(['error' => 'Service temporarily unavailable']);
}

Bulk Writes at Scale: Batch Your Operations or Eat the Latency

Sending one INSERT per document kills throughput. MongoDB PHP driver gives you bulkWrite(). Use it. A single network round-trip can insert 10,000 documents instead of 10,000 separate calls. That's the difference between 2 seconds and 2 minutes.

Bulk writes support inserts, updates, deletes in one batch. Ordered mode stops on first error — useful for sequential operations. Unordered mode runs all operations even if some fail — perfect for loading logs where a few duplicates don't matter.

Batch size matters. MongoDB can't handle an infinite payload. Cap your batches at 10,000 operations or 16MB of data per batch, whichever hits first. Split your array into chunks. Use array_chunk() in PHP to keep your memory sane.

Why wait for each document? Fire a bulk write and move on. Your API response times will thank you.

// io.thecodeforge — php tutorial

$collection = (new MongoDB\Client())->analytics->pageviews;
$records = [];
for ($i = 0; $i < 20000; $i++) {
    $records[] = ['page' => '/product/' . $i, 'timestamp' => new MongoDB\BSON\UTCDateTime()];
}

$chunks = array_chunk($records, 5000);
foreach ($chunks as $batch) {
    $operations = [];
    foreach ($batch as $doc) {
        $operations[] = ['insertOne' => [$doc]];
    }
    $result = $collection->bulkWrite($operations, ['ordered' => false]);
    echo "Inserted: {$result->getInsertedCount()}\n";
}