Nova Mongodb Laravel Package

Getting Started

1. Install the package and its driver dependency:

   composer require francescoprisco/nova-mongodb
   php artisan vendor:publish --tag=nova-mongodb-config   # check actual tag in README
   

   You need the mongodb PHP extension and mongodb/laravel-mongodb ^5.5 already working before this package is useful.

2. Confirm the baseline stack before debugging anything else: PHP 8.2+, Laravel 11/12, Nova 5+, MongoDB 5+. A version mismatch here is the most common cause of "observer not firing" or "resource 500s".

3. Where to look first in the package source:

   • src/MongoDBResource.php — the base class you will extend for every Nova resource backed by MongoDB.
   • src/Connections/MongoDBConnection.php — only relevant if you use transactions.
   • src/Models/ and src/Traits/ — ActionEvent, NovaNotification, MongoNotifiable, HandlesMorphRelations.
   • routes/ (or wherever the notification routes are registered) — these are custom Nova API routes, not Nova's built-in notification endpoints.

4. First use case: take one existing SQL-backed Nova Resource, change it to extend MongoDBResource, point its model at a MongoDB connection, and open the index view. Then create/update/delete a record and inspect the action_events collection to confirm the ModelObserver is logging. This single loop validates resource rendering, connection wiring, and observer registration in one go.

5. For notifications, add the MongoNotifiable trait to your User model and hit GET /nova-api/nova-notifications while authenticated. If that returns JSON, the route registration and notification model are wired correctly.

Implementation Patterns

Resources

• Extend MongoDBResource rather than NovaResource for any resource backed by MongoDB. The base class supplies regex-based search, which is the main behavioural difference from stock Nova resources.
• Keep SQL and Mongo resources side by side in the same app/Nova directory; the "zero SQL dependencies" claim applies to the Mongo-backed path, not the whole app.
• Use HandlesMorphRelations on models/resources that have polymorphic relations, otherwise morph lookups against ObjectIds tend to resolve to the wrong model or return null.

Action events / audit logging

• The ModelObserver is registered automatically for MongoDB models. This means you generally do not call observe() yourself — just create the model and the CRUD logging happens.
• Decide early whether you want the default automatic registration or explicit control. Auto-registration is convenient but makes it harder to conditionally disable logging per model without touching the package config.
• Query ActionEvent directly when building custom audit views; it is a normal MongoDB model, so you can aggregate on it.

Notifications

• Put MongoNotifiable on the User model (or whichever authenticatable Nova uses). Without it, the custom notification routes will not resolve the notifiable and you will get empty lists or 404/500s.
• The package exposes its own route set under /nova-api/nova-notifications. Treat these as the contract for your frontend/toolbar: GET list, POST {id}/read, POST {id}/unread, POST read-all, DELETE {id}, DELETE (all). If you build a custom notification bell, call these instead of Nova's built-in endpoints.
• Prefer read-all and bulk DELETE over loops of single-item calls when clearing a large inbox — each call is a separate round trip and a separate MongoDB write.

Transactions

• MongoDBConnection exists to handle nested transactions. Use it if you have service-layer code that opens a transaction and then calls model code that opens another; the custom connection flattens those instead of throwing.
• MongoDB transactions require a replica set (or sharded cluster). Standalone mongod will fail at runtime regardless of how good the connection class is. Verify rs.status() before blaming the package.

Integration tips

• Configure the Mongo connection in config/database.php as you normally would for mongodb/laravel-mongodb, then let the package's connection class wrap it if you need nested transaction support.
• Keep ActionEvent and NovaNotification in dedicated collections; mixing them into business collections makes cleanup and retention policies awkward.

Gotchas and Tips

• Observer double-logging. Automatic observer registration plus a manual observe() call in a service provider will produce duplicate ActionEvent rows. Grep your providers for the model name if audit counts look inflated.
• Regex search cost. Regex search is unindexed by nature. On collections above a few hundred thousand documents, index the searched fields and consider narrowing the regex, or you will see slow Nova index pages.
• Regex input safety. If the base resource interpolates user input into a Mongo regex without escaping, special characters ((, [, *) can produce errors or unexpectedly broad matches. Sanitise search input in your resource if the package does not.
• Route collisions. The custom /nova-api/nova-notifications routes live under Nova's prefix. If you have your own notification routes or a Nova tool that registers similar paths, check php artisan route:list for shadowing. Route caching after install is worth doing once to confirm the routes are actually loaded.
• Version pinning. mongodb/laravel-mongodb ^5.5 is a hard requirement. An older 4.x driver installed transitively by another package will break the connection class. Run composer why mongodb/laravel-mongodb if transactions or observers misbehave.
• Read/unread state is stored on the Mongo document, not in session or cache. Clearing cache will not reset notification state; you need to call the unread or DELETE endpoints.
• Debugging observers. If action events are not appearing, check in this order: (1) the model uses the Mongo connection, (2) the package service provider is auto-discovered (php artisan about), (3) no withoutEvents()/saveQuietly() call is bypassing the observer, (4) the action_events collection exists and is writable.
• Extension points. Override methods on MongoDBResource for custom search behaviour rather than editing the vendor class; subclass the ModelObserver and register it manually if you need to suppress specific events (e.g. skip logging on bulk imports).
• Nova 5 compatibility surface. Nova 5 changed several resource and notification internals. Since this is a 1.0.0 targeting Nova 5 only, do not expect it to run on Nova 4 — pin Nova in composer.json so a transitive update cannot silently break the resource base class.