Mongo Bundle Laravel Package

Getting Started

• Install the package and the underlying driver extension:

  composer require wizbii/mongo-bundle
  # ensure the PHP extension is present for your platform
  pecl install mongodb
  

• Register the bundle. If there is no Flex recipe, add it manually in config/bundles.php:

  Wizbii\MongoBundle\WizbiiMongoBundle::class => ['all' => true],
  

• Configure a connection. The bundle typically reads a URI + database name from config/packages/wizbii_mongo.yaml (verify the exact tree against DependencyInjection/Configuration.php in the repo — the config shape is the first place to look):

  wizbii_mongo:
      uri: '%env(MONGODB_URI)%'
      database: '%env(MONGODB_DATABASE)%'
  

• Look first at the bundle's Resources/config/services.xml (or .yaml) and the bundle class. That file tells you the service IDs, whether anything is autowired, and whether you get a raw MongoDB\Client / MongoDB\Database or a thin manager wrapper. This is a small bundle — it is not a full ODM like Doctrine MongoDB, so expect to work with the native mongodb/mongodb library objects.
• First use case: inject the database service and do a write + read:

  public function __construct(private \MongoDB\Database $db) {}
  
  public function ping(): array
  {
      $this->db->selectCollection('health')->insertOne(['at' => new \MongoDB\BSON\DateTimeImmutable()]);
      return $this->db->selectCollection('health')->findOne([], ['sort' => ['at' => -1]]);
  }
  

  If autowiring fails, fall back to the explicit service id from the config file (e.g. wizbii_mongo.database or similar).

Implementation Patterns

• Use it as a DI wrapper, not an ORM. The day-to-day value is getting a correctly configured MongoDB\Client/Database injected into services. Persist and query with the native mongodb/mongodb API; don't expect repositories, identity maps, or change tracking.
• Repository-style services per collection. Encapsulate collection access so the rest of the app never calls selectCollection() directly:

  final class OrdersCollection
  {
      public function __construct(private \MongoDB\Database $db) {}
      public function collection(): \MongoDB\Collection { return $this->db->selectCollection('orders'); }
  }
  

  This is the cleanest way to keep BSON specifics out of controllers and Messenger handlers.
• Multiple connections/databases. If your config supports named clients, define one per logical database (e.g. app, analytics, sessions) and inject with @wizbii_mongo.database.app. Aliasing the default is usually a one-liner in your services.yaml.
• Messenger integration. Inject a repository service into handlers and keep the handler small; do the write as the last step so retries are idempotent (use an upsert keyed by a natural id or a _id you generate up front).
• Testing. Two viable approaches: spin up a real Mongo via docker compose in CI (best for index and query correctness), or replace the injected Database/Client with a stub in unit tests. Because the bundle exposes plain library objects, mocking is straightforward — you don't have to fake a UnitOfWork.
• Indexes and schema. Treat indexes as migration artifacts. Run createIndex / createIndexes from a console command or a fixture loader at deploy time, not on the hot path.

Gotchas and Tips

• Verify the service IDs before assuming autowiring works. This is a low-activity bundle with essentially no dependents, so the public surface (service aliases, config keys) may not match the README. Read Configuration.php and the bundle's extension class first — it is faster than debugging a missing-service error.
• mongodb extension required. Without it, mongodb/mongodb installs but fails at runtime. Confirm php -m | grep mongodb on every environment including CI.
• BSON types, not PHP scalars. ObjectId, UTCDateTime, Decimal128, and Binary do not round-trip as plain strings. Store dates as UTCDateTime (not DateTime) unless you have a conversion layer; store ids as ObjectId unless you have a deliberate reason to use strings.
• Connection is lazy. Constructing the client rarely fails; the first operation does. Surface connectivity errors early with a health check at boot rather than discovering them on the first user request. Also watch out for connectTimeoutMS — the default can be long enough to blow up request latency.
• Transactions require a replica set. If your config points at a standalone mongod, startSession() / transaction attempts will throw. Verify the deployment topology before relying on multi-document atomicity.
• Env var URIs want encoding. Passwords with @, :, or / in a MONGODB_URI will be mis-parsed. Either URL-encode or use the separate host/user/password config keys if the bundle supports them.
• Debugging. The Symfony profiler will not show you Mongo queries. Lean on the PHP driver's own logging (mongodb.debug ini setting), server-side slow query logs, and explain() for the queries that matter. Build a small helper command that prints collection stats and index usage.
• Extension point. Because the bundle is thin, the escape hatch is just the library itself: inject a bare MongoDB\Client and configure anything (read preference, write concern, driver options) by hand. Don't fight the bundle if it lacks an option — build the client yourself and register it as a service.
• Bus factor. Zero dependents and low activity mean you should pin the version in composer.json and be prepared to fork or replace. Keep the usage surface small (a handful of repository services) so swapping the bundle for a hand-rolled services.yaml block is a half-day job, not a week.