Laravel Couchbase Laravel Package

Getting Started

Before writing a line of application code, confirm the biggest constraint: this package (last release Feb 2018) targets the Couchbase PHP SDK 2.x (ext-couchbase with the Couchbase\Cluster/CouchbaseBucket style API), not the SDK 3.x that ships today. Run php -m | grep -i couchbase and check the extension version; on PHP 8.x you will almost certainly need a PHP 7.1/7.2 container or a fork. Treat this as a "pin the runtime first, evaluate second" package.

Minimal setup:

1. composer require ort-interactive-gmbh/laravel-couchbase.
2. Register the package's service provider if you are on Laravel < 5.5 (auto-discovery covers later versions).
3. Add a connection to config/database.php — check the README for exact keys, but it is shaped like:

'couchbase' => [
    'driver'   => 'couchbase',
    'host'     => env('CB_HOST', '127.0.0.1'),
    'port'     => env('CB_PORT', 8091),
    'bucket'   => env('CB_BUCKET', 'default'),
    'user'     => env('CB_USER'),
    'password' => env('CB_PASSWORD'),
],

4. Create the bucket in the Couchbase Web Console (http://localhost:8091), give it a RAM quota, and create at least a primary index if you intend to query by anything other than document key: CREATE PRIMARY INDEX ON \bucket` USING GSI;`.
5. Extend the package's Couchbase model base class in your app and set protected $connection = 'couchbase';, public $incrementing = false;, protected $keyType = 'string';.

First use case: a key-addressed, read-heavy collection — user profiles, session/preference documents, product catalog snapshots — where you look things up by ID or a single indexed field. Do not start by porting a relational schema.

Implementation Patterns

Design keys deliberately. Couchbase is fastest when you fetch by key. Use find($id) with composite, human-readable keys (user::<uuid>, order::2024::<ulid>) generated in a creating model event or a repository factory. This lets you bypass indexes for the hottest paths.

Keep where clauses narrow and indexed. User::where('email', $email)->first() works, but only scales if a GSI index exists on email. Every new query shape in the app should come with a matching CREATE INDEX in your deployment scripts.

Denormalize instead of relating. Eloquent relationships against a document store are unreliable here. Embed related data in the document, or store a reference ID and load it explicitly through a repository. This also keeps reads to a single key lookup.

Wrap models in repositories. Put Couchbase access behind UserRepository, CatalogRepository, etc. The package's query builder has gaps versus core Eloquent; the repository boundary lets you swap in raw N1QL, the official SDK, or a different backend without touching controllers.

Use raw/N1QL as the escape hatch. For aggregations, GROUP BY, joins across document types, or anything the builder doesn't cover, drop to a raw query through the connection rather than fighting the builder. Keep these parameterized ($1, $2) to avoid injection and to reuse the query plan cache.

Treat indexes and design documents as code. There are no meaningful migrations. Keep a database/couchbase/ directory of N1QL scripts (CREATE INDEX, CREATE PRIMARY INDEX, view definitions) and run them from an artisan command or deploy step. This is your schema.

Test against a real bucket. Use the couchbase Docker image, flush the bucket in setUp, and run integration tests against it. Mocking the SDK hides index and consistency behavior that will bite you in production.

Watch connection lifecycle in workers. Long-running queue workers and Octane-style runtimes can outlive an SDK connection. Create connections per job or add a health check/reconnect in your base repository.

Gotchas and Tips

• SDK 3 incompatibility is the headline risk. The 2018 API (Couchbase\Cluster, bucket objects) differs from today's SDK. If you cannot pin PHP 7.x, budget for a fork or a thin custom repository over the official SDK.
• No auto-increment IDs. Set $incrementing = false and $keyType = 'string', and generate keys yourself. insertGetId() will not do what you expect.
• Missing Eloquent surface area. Expect gaps around relationships, whereHas, some where* variants, orWhere grouping, and orderBy on unindexed fields. Read the builder source before assuming a method exists.
• Unindexed queries silently time out. A where on a large bucket without a GSI will full-scan and may blow the request timeout. Reproduce in the Web Console's Query tab or cbq CLI and check the execution plan.
• Consistency vs. latency. Reads may hit a stale index. When correctness matters, request request_plus/at_plus scan consistency at the cost of latency; don't set it globally.
• Limits: ~20 MB per document and 250 bytes per key. Keep keys short, keep blobs in object storage, and store only metadata and pointers in Couchbase.
• Dates are strings in the document. Eloquent timestamps work, but range queries need a consistent format (prefer ISO-8601 or epoch integers) and an index on that field.
• Debugging: use DB::connection('couchbase')->enableQueryLog() if the connection logs, otherwise lean on the Couchbase UI's completed-requests and query monitors. Catch CouchbaseException subclasses and translate them into domain errors rather than leaking SDK exceptions.
• Extension points: subclass the package's connection and model base to add retries, metrics, and JSON normalization. Wrapping is safer than monkey-patching; the package is unmaintained, so anything you customize becomes yours to maintain.
• Evaluate the exit path early. Given the 2018 release and low activity, design repositories so migrating to the current official Couchbase PHP SDK (or another store) is a contained change, not a rewrite.