jenssegers/mongodb-lite
Lightweight MongoDB integration for Laravel. Provides Eloquent-style models backed by MongoDB collections, letting you query, insert, and manage documents with familiar Laravel syntax while keeping dependencies and footprint small.
v1.1.0 is a compatibility pin to Laravel 4.2, not a feature release — so the first hour is proving the stack resolves and the container binds before you write a single document.
Minimum viable setup on 4.2:
php artisan --version must say 4.2. On 4.0/4.1 the ~4.2 bump is potentially breaking; on 5.x+ the constraint will refuse to resolve or drag illuminate/* backwards. Fix this before anything else.composer require jenssegers/mongodb-lite:~1.1 — read solver output closely. 4.2-era constraints conflict aggressively with anything else pinned to ~5.0, and a silent downgrade of a shared illuminate/* component is the classic failure.app/config/app.php → providers. 4.2 has no package auto-discovery; until this line exists nothing is bound and every call dies with "class not found."aliases in the same file if the README documents one. Pick a distinctive alias and immediately check it doesn't collide — see Gotchas.php artisan config:publish jenssegers/mongodb-lite. In 4.2 this is the correct command (vendor:publish doesn't exist yet).app/config/packages/jenssegers/mongodb-lite/ — host, port, database, credentials.php artisan dump-autoload after every manual app/ change; 4.2 caches hard and stale autoload is the single most common early failure.Where to look first. The package's service provider is the real documentation. Read register() and boot() to see exactly what gets bound into the container and under which keys — that tells you which class to type-hint and how to override behaviour. Then read the published config. Only after that go looking for the base model class you're expected to extend.
First use case — a single round-trip. Define one model against a throwaway collection and prove the chain end to end:
class Widget extends Jenssegers\MongodbLite\Model
{
protected $collection = 'widgets';
}
Widget::create(['name' => 'demo', 'qty' => 1]);
$w = Widget::where('name', 'demo')->first();
If that works, the provider, config, driver, and autoload are all correct. If it doesn't, you've narrowed the problem to one of those four before writing any real code.
Model-per-collection with an explicit $collection. Don't rely on class-name-to-collection guessing. Declare the collection on every model — MongoDB collections are case-sensitive and a silent pluralisation mismatch is a nasty half-hour.
Wrap the package behind your own interface from day one. This is the highest-leverage pattern given the package's status:
interface WidgetRepository { /* ... */ }
class MongoWidgetRepository implements WidgetRepository
{
public function __construct(protected Widget $model) {}
}
Bind it in a service provider, inject the interface (not the facade) into controllers, jobs, and commands. When this package goes dark — and plan for it going dark — the replacement is a rebind, not a codebase-wide grep.
Prefer constructor injection over facades. Facades work, but they make it impossible to substitute a fake in tests and they hide the dependency during code review. Resolve models and repositories through the container.
Use the fluent builder like Eloquent, but only for the subset that maps to MongoDB. Where/equality/first/get/create/update/delete are the safe core. Anything that smells like a SQL join has no MongoDB equivalent — model it as two collections and denormalise, or embed. Don't fight the builder into SQL shapes; write the query you'd write in the Mongo shell and translate it.
Schema-less means your code owns the schema. There are no migrations here. Enforce shape at three points:
_id → string, dates → DateTime, numbers not strings).validate()-style method or form-request equivalent before persistence.Seeders are your schema documentation. With no migrations, db:seed-style seeders and fixture factories are the closest thing to a schema definition. Keep them current; they're also what your integration tests reuse.
Integration-test against a real MongoDB. Do not fake this with SQLite or an in-memory store — the whole point is document semantics. Stand up a disposable Mongo container/database per test run, point the test-environment config override at it, and drop the database in teardown. Keep assertions at the repository boundary so the same suite runs against a future replacement.
Environment-specific config, not env-specific code. Put host/database/credentials in app/config/packages/jenssegers/mongodb-lite/ and use the environment/ subfolder for per-env overrides. Never branch on App::environment() inside a model or repository.
Feature-flag new usage. If you're adding MongoDB persistence to an existing 4.2 app, gate the new read/write paths behind a config flag so you can revert without a deploy.
Forgotten registration is the #1 failure. Symptoms: "class not found," "target not instantiable," or the facade resolving a wrong class. Checklist for any "doesn't exist" error: provider in app/config/app.php → alias in the same file → dump-autoload → config published. In that order.
Facade alias collisions. Short aliases are dangerous in a 4.2 app with a big dependency set. Client, Api, Mongo, DB are all plausible. Pick a distinctive alias (e.g. MongoLite) and grep the service providers of everything else in composer.json before committing.
Config precedence bites. Editing the package's own config/config.php inside vendor/ works until the next composer update silently overwrites it. The correct override path is app/config/packages/jenssegers/mongodb-lite/ — and if you have an environment subfolder, that takes precedence over the root file, which surprises people in the opposite direction (prod edits that don't apply locally).
_id handling will cost you an afternoon. Mongo ObjectId is not a PHP string. Expect to see:
toArray() transform._id is roughly time-ordered but no substitute for a real timestamp field.No transactions on a legacy stack. Older MongoDB server/driver combinations don't give you multi-document atomicity. Design writes to be idempotent and single-document, or accept eventual consistency and write compensating logic.
Driver version mismatch is a silent killer. A PHP Mongo driver newer than the server (or vice versa) often connects fine and fails on specific operations. Pin the ext-mongo/driver version in composer.json's platform block and document it alongside the host baseline.
Autoload-era breakage. This is a PSR-0-generation package. Moving files, renaming classes, or adding namespaces without php artisan dump-autoload produces "class not found" errors that look like registration problems but aren't. Make dump-autoload the first thing you try.
Don't assume Eloquent semantics. Relations, eager loading, save() lifecycle events, and casting may be present, partially present, or absent. Verify each before building on it — the package is lightweight by design, and the description explicitly says "Eloquent-style," not "Eloquent."
Debugging queries. When a query returns nothing, don't reach for the ORM first — reproduce the same query in the mongo shell against the same database. That isolates "my query is wrong" from "the connection is wrong" in under a minute. For connection issues, hit the driver directly once; if the driver connects and the model doesn't, it's a config/provider problem, not a Mongo problem.
Where to extend. The service provider's registration points, the config file, and the base model class are your three extension surfaces. Anything deeper (query-builder behaviour, connection handling) requires a fork — and if you fork, do it deliberately, with a named owner and a version pin, not as a hotfix in vendor/.
Budget for the exit. The most important tip for a day-to-day developer on this package: keep your repository interface narrow and your model classes boring. Every extra method you hang off the package raises the cost of the migration you already know is coming.
How can I help you explore Laravel packages today?