- What is mpociot/couchbase and what does it add to Laravel?
- mpociot/couchbase is a Laravel integration for Couchbase that wraps the Couchbase PHP SDK in Eloquent-style models, a fluent query builder, native key-value operations, and N1QL query support. It also ships a service provider and config integration so JSON documents in a bucket feel like familiar Laravel records. Under the hood it is a translation layer that presents a document store through an Eloquent-shaped API, not a relational driver.
- How do I install mpociot/couchbase in a Laravel application?
- In practice, expect a compatibility fork rather than a clean composer require. The package has zero dependents and reads as a republished fork of mpociot/couchbase, so do not assume clean Packagist resolution or that extra.laravel.providers auto-discovery is declared. Plan to pin a commit, possibly add a VCS repository entry in composer.json, and register the service provider by hand. Confirm the required PECL extension version in the target environment before you start.
- Which Couchbase PHP SDK and PECL extension version does this package need?
- The driver speaks the 2.x Couchbase PHP SDK API surface, using classes such as Cluster, Bucket, and N1qlQuery. If your environment carries the 3.x extension, those classes are gone or reshaped and the package will not work unmodified. Check which PECL version is actually present and whether the 2.x line can be baked into a pinned, reproducible Docker image before circulating any estimate.
- Does mpociot/couchbase support Laravel 10 or 11 and PHP 8?
- The package targets an older Laravel release and the 2.x Couchbase extension, so running it on a current Laravel and PHP 8.x realistically means maintaining a compatibility fork. Do not assume it installs and runs on Laravel 10 or 11 without changes. Budget the fork as work item one and validate a spike against your actual stack before committing.
- Can I use Eloquent relationships, joins, or whereHas with Couchbase models?
- Relational features are stubbed, not implemented: joins, whereHas, withCount, composite keys, auto-increments, and DB::raw of relational SQL do not necessarily error, but they can degrade or return plausible, wrong results. Every relational query in a candidate feature is a rewrite candidate until someone has read it and proven it against a real cluster. This package fits key-addressed, document-shaped workloads, not relational querying.
- How do I run N1QL queries through this package?
- N1QL is Couchbase's SQL-like query language, and the package exposes it through its fluent query builder so you can filter and look up JSON documents by non-key fields. It is the right tool for document queries, but it should not be treated as a stand-in for relational joins or aggregate semantics. Verify each generated query against a real cluster rather than trusting the Eloquent-shaped surface.
- Why does a query right after save() return stale or empty results?
- Writes land in the bucket, while N1QL reads go through the indexer, which lags behind. A save() followed by a query on a non-key field can therefore return stale or empty data. This is a production-class defect rather than a developer inconvenience, so each aggregate needs an explicit read-your-writes test against a real cluster.
- Is mpociot/couchbase maintained and safe to use in production?
- Treat adoption as an in-house fork: there is no active maintainer, no dependents, and no security patch path. Pin the commit, own the code, and name an engineer with allocated time to maintain it. If your 12-month roadmap needs scopes, collections, transactions, or modern Capella ergonomics, this is a dead end regardless of spike results.
- When is this package a good fit versus a relational database or Laravel's Couchbase cache and session drivers?
- It is a reasonable fit for aggregates that live on point reads, such as catalog items, session state, audit events, and device records stored as JSON documents addressed by key. For anything whose center of gravity is relational querying, the familiar Eloquent surface conceals a category error and your estimate will be wrong. Also evaluate whether Laravel's cache and session drivers over Couchbase alone, without the database driver, would satisfy the requirement.
- How should I test a Couchbase-backed Laravel feature before committing to the package?
- Write the acceptance test down before writing code: one document-shaped aggregate, four operations, a latency ceiling, and a specific cluster to run against. Answer the two gates first, the PECL extension version and the packaging story, since both are non-trivial and answerable in an afternoon. Only then decide whether to fork and adopt the package.