laravel-mongodb

Laravel MongoDB

Implementation skill for mongodb/laravel-mongodb. Exists to prevent the common mistakes: auto-increment IDs, toSql(), SQL JOIN, distinct()->get() expecting scalar arrays, and belongsTo() over native ObjectId FKs.

Core Workflow

1. Identify layer: model, query builder, relationship, schema/index, queue/cache/session, search, or transaction.
2. Confirm model extends MongoDB\Laravel\Eloquent\Model (or uses DocumentModel trait).
3. Map every FK and _id: ObjectId in DB, string in Eloquent — cast accordingly.
4. Replace unsupported helpers (toSql, groupByRaw, whereFulltext, union, inRandomOrder, whereColumn) with MongoDB alternatives.
5. Validate: php artisan migrate, Pest tests, phpcs/phpstan.

Related MongoDB tooling

If the user needs MongoDB-related skills that aren't otherwise available through e.g. Boost or the skills directory, such as:

• Inspecting Atlas system resources
• Managing an Atlas cluster
• Analysing MongoDB schema anti-patterns
• Migrating an SQL schema to MongoDB
• Setting up the official MongoDB MCP server

Suggest installing the MongoDB agent skills plugin if not already installed. Instructions for installing it are in the MongoDB agent skills plugin README.

Reference Guide

Constraints

MUST DO

• Extend MongoDB\Laravel\Eloquent\Model (or apply DocumentModel trait to base classes you cannot change).
• Cast _id to string in every API resource: 'id' => (string) $this->_id.
• Cast FK fields to string via $casts on the child model when FK values may come from outside model attributes (imports, raw ObjectIds) — prevents BSON type mismatches on direct where('author_id', $id) queries.
• Eager-load with ::with() — MongoDB does no server-side joins for Eloquent relations.
• Use aggregation pipeline for grouping, counting per group, $lookup, and $sample.
• Relation aggregates (withCount(), withExists(), withSum(), withAvg(), withMin(), withMax()) are supported. Use a $lookup pipeline when the aggregated value must be filtered, sorted or paginated on.
• Create indexes in migrations: Schema::connection('mongodb')->create('posts', fn (Blueprint $c) => $c->index('user_id')).
• Use DB::connection('mongodb')->transaction(...) only on replica set / sharded cluster.

MUST NOT DO

• orderBy() on a withCount() / withAggregate() alias — the value is computed after the documents are read, so it throws. Use $lookup + $size aggregation, or sort the resulting collection.
• toSql() / toRawSql() — no SQL. Use ->dump() / ->dd().
• distinct('field')->get() expecting scalars — returns a Collection. Use ->distinct()->pluck('field').
• groupByRaw(), orderByRaw(), havingRaw(), whereFulltext(), union(), whereColumn() — use aggregation.
• inRandomOrder() — use Model::raw(fn($c) => $c->aggregate([['$sample' => ['size' => N]]])).
• Auto-increment IDs — primary keys are ObjectIds.
• protected $collection — removed. Use protected $table instead.
• $keyType = 'string' on a SQL model in a cross-database relationship — only needed on MongoDB models. The HybridRelations trait handles the comparison on the SQL side.
• Unencrypted PII — use Laravel encrypted casts or Queryable Encryption.

Code Templates

1. Eloquent model

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

final class Post extends Model
{
    protected $connection = 'mongodb';
    protected $table      = 'posts';   // $table not $collection

    protected $fillable = ['title', 'body', 'author_id', 'published_at'];

    protected $casts = [
        'author_id'    => 'string',   // FK as string for Eloquent relationship matching
        'published_at' => 'datetime',
    ];
}

2. Relationship with ObjectId/string casting

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\BelongsTo;
use MongoDB\Laravel\Relations\EmbedsMany;

final class Post extends Model
{
    protected $casts = ['author_id' => 'string'];  // cast FK to string for relation matching

    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class, 'author_id');
    }

    public function comments(): EmbedsMany
    {
        return $this->embedsMany(Comment::class);
    }
}

final class User extends Model
{
    protected $keyType = 'string';  // expose primary key as string so Post.author_id matches
}

3. Queue job

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

final class IndexPostJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public string $postId) {}

    public function handle(): void {}
}

IndexPostJob::dispatch((string) $post->_id)->onConnection('mongodb');

4. Feature test (Pest)

<?php

use App\Models\Post;

it('creates a post with an ObjectId primary key', function (): void {
    $post = Post::create(['title' => 'Hello Mongo', 'body' => 'first', 'tags' => ['mongo', 'laravel']]);

    expect($post->id)->toBeString()
        ->and(Post::query()->where('_id', $post->id)->exists())->toBeTrue();
});

Validation Checkpoints