Laravel Mongodb Laravel Package

Getting Started

The package wires Eloquent-style models to a document store, so the fastest path is to treat it as "Eloquent with _id instead of id" and verify that assumption before writing feature code.

1. Install and publish config, then set the connection in config/database.php (or the package's own config file) and in .env. Confirm the extension/driver is present in your PHP build before debugging anything else.
2. Create a first model and a migration-equivalent (collection/index creation) for a single, simple collection. Do not start with relations or embedded documents.
3. Run a create → find → update → delete round trip in php artisan tinker. Inspect the raw document in the database shell, not just the model's toArray(), so you can see exactly which key the identifier landed in.
4. Only after that, look at the package's tests for embedded/sub-document behaviour — that is where the semantics differ most from relational Eloquent, and where this release changed things.

First use case to target: a single collection with a small embedded sub-document array (e.g. addresses), written and read back through the model. This exercises the identifier handling that v5.0.3 touched, without the confounding factor of relations.

Implementation Patterns

Identifier handling. Historically the package auto-converted an id attribute to _id on both root documents and sub-documents. As of v5.0.3 that implicit conversion is removed. The reliable pattern now is to be explicit everywhere:

• Declare the primary key on each model (protected $primaryKey = '_id';) and let the package assign it, rather than relying on a magic id → _id mapping.
• For embedded/sub-documents, set the key explicitly in the sub-document class or in the array you push. Do not assume a nested id will be rewritten for you.
• When hydrating from external input (API payloads, imports), normalise id → _id in a form request, DTO, or model mutator. Keeping that mapping in one place is far cheaper than auditing every call site later.

Model and query patterns.

• Use query-builder style filters (where, whereIn, orderBy) as you would in Eloquent, but keep an eye on array/embedded field paths — dot notation (addresses.city) is the mental model, and it does not map cleanly onto Eloquent's relation helpers.
• Prefer $model->getKey() / $model->getKeyName() over hardcoding _id in application code. This keeps the code honest if the package changes again and makes the intent obvious to reviewers.
• For sub-documents, model them as dedicated classes with their own casts rather than free-form arrays. It costs a little boilerplate and pays back the moment you need validation or partial updates.

Workflows and integration tips.

• Wrap multi-collection writes in transactions only if your deployment actually supports them; otherwise design for idempotent writes and accept eventual consistency.
• Keep index creation in versioned, re-runnable scripts alongside migrations, and create indexes for the fields you filter and sort on before you load-test — document stores punish missing indexes harder than relational databases do.
• Use raw access (DB::connection('...')->collection(...) or the package's equivalent) as an escape hatch for bulk operations and diagnostics, but keep it out of domain code.
• In tests, assert on the persisted document shape, not just the model attributes. The gap between "what the model exposes" and "what is stored" is precisely where identifier-conversion changes bite.

Gotchas and Tips

The v5.0.3 change is the one to plan around. Removing automatic id → _id conversion for documents and sub-documents is a silent behavioural change, not a loud one. Code that previously worked because a nested id was rewritten will now write a literal id field alongside _id, producing documents with two identifiers. Symptoms to watch for:

• Duplicate or unexpected keys in stored documents (id and _id present).
• Lookups by _id returning null for records that clearly exist.
• Sub-document updates that appear to no-op because the query matched on the wrong key.

Debugging approach. When an identifier-related bug appears, drop to the database shell and read the raw document first. Comparing the stored document against $model->getAttributes() localises the problem in one step: if the model has _id and the document has id, the conversion layer is the culprit; if both agree, the bug is in your query.

Config quirks.

• Connection config is often duplicated between .env and the package config; a stale cached config (php artisan config:clear) is a common cause of "my change did nothing".
• Auth/DSN settings differ between local and cluster environments — assert the connection at boot in non-production rather than discovering it on first write.
• If you use model caching or serialisation to queues, remember that serialised models carry the identifier as it existed at serialisation time. After an upgrade, in-flight jobs queued under the old conversion behaviour can deserialise into a model whose key no longer resolves.

Extension points worth knowing.

• Model events (creating, saving) are the natural place to enforce identifier normalisation centrally if you cannot touch every call site.
• Custom casts and accessors let you present an id-shaped API to consumers while storing _id internally — useful for keeping a public JSON contract stable across this upgrade.
• If the package exposes a schema-builder or index helper, prefer it over hand-rolled index commands so index definitions stay reviewable alongside the models.

Upgrade checklist for this release. Search the codebase for 'id' in sub-document definitions, mass-assignment arrays, and seeders; grep tests for assertions on id in nested structures; re-run your model round-trip smoke test on embedded documents specifically. Pin the version in composer.json and treat the patch number as advisory — the change described here is semantic, not cosmetic.