Laravel Mongo Queue Monitor Laravel Package

Getting Started

1. composer require mongodb/laravel-mongodb — note the vendor changed over time (jenssegers/mongodb → mongodb/laravel-mongodb) and the model namespace moved with it (Jenssegers\Mongodb\Eloquent\Model in 4.x, MongoDB\Laravel\Eloquent\Model from 5.x). Confirm the installed namespace in vendor/ before copy-pasting examples.
2. Install the PHP extension, not just the library: pecl install mongodb and add extension=mongodb.so.
3. Add a mongodb connection in config/database.php (dsn / MONGODB_URI), then set DB_CONNECTION=mongodb or keep MySQL as default and opt in per model via protected $connection = 'mongodb';.
4. First use case: start with a non-critical, flexible-schema collection — audit logs, event payloads, webhook bodies, third-party API responses. It gives you a real workload while the relational core stays untouched.

Where to look first: the README's Eloquent section, the base Model class (for $collection, $guarded, casts, and the embeds*/references* relations), and the package's own tests/ directory — it documents real behaviour far better than the docs for corner cases.

Implementation Patterns

• Model basics. Extend the package's base model, set $collection, prefer an explicit $fillable over the tutorial-common $guarded = [], and cast _id appropriately so route-model binding and JSON serialisation behave.
• Relations. Use embedsOne/embedsMany for data you always read together (denormalised, single round-trip) and referencesOne/referencesMany / belongsTo / hasMany for entities that are queried independently. Embedding is cheap to read and expensive to update in bulk — decide per access pattern.
• Querying nested data. Dot notation throughout: where('address.city', 'Berlin'), where('tags', 'php') (scalar matches inside arrays), where('meta', 'exists', true), whereIn, whereBetween, orderBy.
• Aggregation. Model::raw(function ($collection) { return $collection->aggregate([...]); }) is the escape hatch for $lookup, $facet, $graphLookup, $unwind. Without raw() the builder rewrites your pipeline; with it you own the driver semantics.
• Atomic updates without reading. ->push('tags', 'x'), ->pull(...), ->increment('views'), ->unset('field'), and updateOrCreate/upsert — these avoid the read-modify-write race that plagues naive document editing.
• Hybrid architecture. Keep money, identity, and anything needing joins/transactions in MySQL; put documents, logs, and variable-shape payloads in Mongo. There are no cross-database joins — denormalise deliberately or assemble in PHP.
• Index management. Create indexes early, in a migration or a dedicated db:indexes command (the schema builder has limited support here), and commit them to source control. A Mongo collection without indexes is a future incident.
• Service integration. The package also ships session and queue drivers — handy for a single-datastore setup, but validate throughput before using Mongo as your queue backend at scale.

Gotchas and Tips

• _id type mismatches are silent. where('_id', $request->id) with a string returns nothing on an ObjectId collection. Cast to ObjectId (or use the model's typed key). This is the single most common "it just returns empty" bug.
• No schema means no guardrails. Typos in field names create new fields instead of erroring. Centralise field names in constants or a document class; write a validation layer on write.
• Transactions require a replica set (or sharded cluster). On a standalone mongod, DB::transaction() throws — a frequent surprise when moving from local Docker to production.
• Driver extension version drift. Pecl mongodb and the library version are pinned together; a stale extension breaks with confusing class-not-found errors. Lock both in CI.
• Version churn. This release's notes contain only the string laravel-mogodb-4 — no changelog, no breaking-change list, no migration guide. Treat that as a red flag: read vendor/*/CHANGELOG.md, diff the config stub and model namespaces, and check composer why before upgrading a production app. Namespace and config-key renames have happened in past majors.
• Debugging slow queries. Laravel's DB::listen does not see Mongo traffic. Use ->explain() on the builder, or set profiling on the server (db.setProfilingLevel(2)) and read system.profile; look for COLLSCAN in the winning plan.
• count() is misleading on large/filtered sets — prefer countDocuments semantics and remember pagination requires a stable sort (usually _id).
• Large result sets. ->get() hydrates everything into memory. Use ->cursor() or chunkById for exports and batch jobs.
• Sorting and collation. Strings sort by raw UTF-8 bytes by default; MongoDB-side case-insensitive search needs a collation index or a normalised lowercase field — where('name', 'like', ...) only becomes regex, which is unindexed unless anchored.
• Extension points. Add Builder::macro(...) for repeated pipeline fragments, subclass the query builder on a model for domain-specific scopes, and wrap complex pipelines in repository methods so raw() closures stay out of controllers.