Mongodb Fixtures Bundle Laravel Package

Getting Started

First, the framework reality check. Despite being told to approach this as a Laravel developer, this is a Symfony bundle (Bundle subclass, config/bundles.php registration, Doctrine MongoDB ODM). Nothing here maps to Eloquent, migrations, or php artisan. The conceptual equivalents are useful — fixtures ≈ seeders, DocumentManager ≈ Eloquent's connection manager, purge-between-tests ≈ RefreshDatabase — but the mechanics are Symfony's. If you are actually in Laravel, this package is not usable as-is; you would reach for a Doctrine MongoDB ODM integration and hand-roll fixture loading instead.

Assuming a Symfony app with doctrine/mongodb-odm-bundle and mapped documents:

1. Install as a dev dependency — it is test tooling, not runtime code:

   composer require --dev graviton/mongodb-fixtures-bundle
   

2. Register the bundle in config/bundles.php (typically only in test/dev envs).
3. Confirm a working doctrine_mongodb connection and at least one mapped Document, because every fixture class must be a mapped ODM document.
4. Where to look first: composer.json for the exact Symfony/ODM version constraints, then src/ for the trait (likely something like MongoDBFixturesTrait) and any base test case it ships, then the repo's tests/ directory to see the actual fixture file format. Because the package advertises being dependency-free (no nelmio/alice, no fzaninotto/faker), the fixture format is almost certainly plain PHP arrays rather than Alice YAML — verify this before writing fixtures.
5. First use case: an integration test that needs a known set of documents in MongoDB before asserting on a repository query or a controller response. Write one fixture file with two or three documents for a single collection, load it in setUp(), assert a query returns what you expect. That one loop tells you 80% of what the package does.

Implementation Patterns

Base test case + trait. The intended pattern is a trait mixed into a KernelTestCase/WebTestCase. Put it in an abstract MongoDbTestCase so every functional test inherits loading and cleanup:

abstract class MongoDbTestCase extends WebTestCase
{
    use MongoDBFixturesTrait;

    protected function setUp(): void
    {
        parent::setUp();
        static::bootKernel();
        $this->loadFixtures(['users.php', 'orders.php']);
    }

    protected function tearDown(): void
    {
        $this->purgeCollections(); // or whatever the trait names it
        parent::tearDown();
    }
}

Fixture files as data. Expect each file to return an array of document data (or documents) keyed by the mapped class. Keep them small and purpose-built per test class — users_basic.php, users_with_orders.php — rather than one giant seed file. Because there is no Faker, centralise reusable array builders in a FixtureFactory helper (plain PHP methods returning arrays) so you don't copy-paste email addresses and IDs.

Load per-test when scenarios diverge. Override setUp in subclasses or call loadFixtures([...]) inside individual test methods for variations. Avoid loading everything globally via PHPUnit bootstrap; per-test loading keeps failures attributable.

Purge before, not just after. MongoDB collections persist across test runs if a prior run crashed. Purge in setUp (idempotent starting state) as well as tearDown, or use a dedicated test database name per environment and drop it entirely at suite start.

Web/client tests. Boot the kernel after fixtures are loaded if your test client boots its own kernel; or load fixtures via the container's document manager and reuse that same manager. Mixing two document manager instances across two kernels is a classic source of "fixtures are there but the test can't see them."

Relations. If your documents use DBRefs or embedded documents, the loader generally persists in file order. Order fixtures so referenced documents come first, and give documents explicit IDs in the fixture arrays so you can hard-code references without querying for the generated ID.

Gotchas and Tips

• "Drop-in replacement for liip/test-fixtures-bundle" is a claim, not a contract. Liip's bundle carries annotations/attributes (@DisableDatabaseCache), Alice-based YAML, and ORM support. This one is MongoDB-only and dependency-free, so anything Alice-shaped will not work. Read the source rather than assuming API parity; with zero stars and zero dependents, the README is the only spec you get.
• Purging can drop indexes. If purge drops collections rather than deleting documents, unique indexes and TTL indexes vanish, and tests behave differently on the second run than the first. Prefer deleteMany([]) semantics, or re-run index creation after purge.
• MongoDB is not transactional by default. Unlike a SQL RefreshDatabase with a transaction rollback, isolation here is real writes to a real database. Any test that crashes mid-run leaves data behind — hence purge-on-setup. On a replica set you could use transactions, but a fixture bundle that's "dependency free" is unlikely to wire that up for you.
• Parallel test runs will collide. PHPUnit's paratest or process isolation against the same database name produces flaky, order-dependent failures. Use a per-process database suffix (test_db_%s with getmypid() or TEST_TOKEN) in the connection config.
• Mapping errors surface as loader errors. A fixture entry for an unmapped class, or with a field the ODM doesn't know, usually fails at persist/flush time with a cryptic driver exception. Validate that each fixture key is a real Document class and that field names match the mapping (not your entity property names, if you use #[Field(name: ...)]).
• No Faker means fixture brittleness. Hand-written data drifts: duplicated unique values, missing required fields, dates in the past that break "recent orders" queries. Build a tiny builder helper and set dates relative to new \DateTime() rather than hard-coded strings.
• Pin the version and vendor the knowledge. A package with no stars and no dependents has no community safety net; a composer update can break you silently. Use an exact constraint ("graviton/mongodb-fixtures-bundle": "1.2.3") and skim the diff before bumping.
• Extension points to look for: fixture directory path configuration (so you can use tests/Fixtures/Mongo rather than whatever default it assumes), and whether the trait exposes a hook to substitute a custom document manager — useful if you run multiple ODM connections.
• If it doesn't fit, the exit ramp is cheap. doctrine/mongodb-odm-bundle ships a data-fixtures command (doctrine:mongodb:fixtures:load), and hautelook/alice-bundle or doctrine/data-fixtures gives you a maintained path for the same job. Since this bundle's value is "small and dependency-free," a 30-line trait of your own that loads PHP arrays into the document manager is a credible replacement if maintenance stalls.