Couchbase Bundle Laravel Package

Getting Started

This is a thin Symfony bundle that wires the Couchbase PHP SDK 2.x (ext-couchbase extension, not the newer couchbase/couchbase Composer package) into the service container. It is minimal by design — no ODM, no cache/session adapters, no profiler integration. Treat it as a connection factory, not a framework.

Minimum steps:

1. Confirm your runtime. You need the ext-couchbase PHP extension (the 2.x C extension) compiled against a compatible version of libcouchbase. Verify with php -m | grep couchbase. If you only see couchbase from the Composer package (couchbase/couchbase 3.x/4.x), this bundle will not work — you're on the wrong SDK.
2. Install the bundle:

   composer require simonsimcity/couchbase-bundle
   

3. Register the bundle. On Symfony 4+ add it to config/bundles.php:

   return [
       // ...
       SimonSimCity\CouchbaseBundle\CouchbaseBundle::class => ['all' => true],
   ];
   

   On Symfony 3.x, add it to app/AppKernel.php.
4. Configure a cluster and bucket under the couchbase key in your config:

   couchbase:
       dsn: '%env(COUCHBASE_DSN)%'   # e.g. couchbase://127.0.0.1
       options:
           username: '%env(COUCHBASE_USER)%'
           password: '%env(COUCHBASE_PASS)%'
       buckets:
           default:
               name: 'default'
               password: ''
   

5. Look first at src/DependencyInjection/Configuration.php and the extension class. The bundle exposes roughly one cluster service and one bucket service per configured bucket. Run bin/console debug:container couchbase (or --show-private) to see exactly which service IDs were registered — the exact IDs are the first thing to confirm before writing any application code.

First use case: inject the bucket service into a small repository class and do a get/upsert:

final class UserRepository
{
    public function __construct(private \CouchbaseBucket $bucket) {}

    public function find(string $id): ?array
    {
        try {
            return $this->bucket->get("user::{$id}")->value;
        } catch (\Couchbase\Exception\DocumentNotFoundException) {
            return null;
        }
    }

    public function save(string $id, array $doc): void
    {
        $this->bucket->upsert("user::{$id}", $doc);
    }
}

Implementation Patterns

Always wrap the bucket in your own service. The bundle hands you a CouchbaseBucket; treat that as infrastructure. Repositories that accept CouchbaseBucket in the constructor give you a place to centralise key-prefixing, document hydration, exception mapping (DocumentNotFoundException → null), and TTL defaults.

Bind by service ID, not autowiring. This bundle predates Symfony's autowiring conventions and registers named services. Either reference the bucket ID explicitly in a service definition:

services:
    App\Repository\UserRepository:
        arguments: ['@couchbase.bucket.default']

or add an alias so autowiring works:

services:
    App\Repository\UserRepository:
        arguments: ['@couchbase.bucket.default']
    # ...

Confirm the exact ID via debug:container before committing — do not guess from documentation.

Use multiple buckets for isolation. Because each entry under buckets: produces its own service, you can cleanly separate concerns (sessions vs. documents vs. counters) without sharing state. This is the most useful thing the bundle does out of the box.

N1QL via the cluster, not the bucket. For anything beyond key/value lookups you'll need the cluster service. The bundle registers it; inject that into a dedicated QueryService so you're not passing a cluster object through your domain code:

$res = $this->cluster->query(
    'SELECT META(u).id AS id, u.* FROM `users` u WHERE u.email = $email',
    ['namedParams' => ['email' => $email]]
);

Key conventions matter more than usual. Couchbase is a key/value store at heart. Adopt a strict prefix scheme (user::, order::, session::) and document it. The bundle does nothing to help you here, and ad-hoc keys are the #1 source of "why is this document invisible" bugs.

Testing strategy. CouchbaseBucket is a concrete class from the extension, so mocking it is painful. Two practical options: (a) put a BucketInterface of your own in front of it and mock that, or (b) run tests against a real Couchbase container (couchbase/server Docker image) and flush the bucket between tests. Option (b) is usually faster to set up than fighting the mocking.

Health checks. Expose a small console command or health endpoint that calls cluster->manager()->info() (or your bucket's getDesignDocuments()) so you find out about a dead node before your users do. The bundle does not provide this.

Gotchas and Tips

This is SDK 2.x only — this is the biggest trap. The bundle targets ext-couchbase (the 2.x C extension), which Couchbase has been de-emphasising for years in favour of couchbase/couchbase (SDK 3.x/4.x, pure PHP). If you're starting a new project on Couchbase 7+, you almost certainly want the modern Composer SDK and a small custom service definition instead of this bundle. Check before you commit.

Extension, not library. If php -m doesn't list couchbase, the bundle will fail at container compile time or on first use with a class-not-found error. There is no graceful degradation. Add the extension to your Dockerfile / CI matrix explicitly.

Connection is established early. The bundle constructs the cluster and buckets as DI services. In Symfony's default lazy-ish setup this is usually fine, but in CLI commands that touch unrelated code, you can pay the connection cost. If you notice slow bin/console startup after installing, mark the bucket services public/lazy or defer access behind a factory you control.

Couchbase Server compatibility is not the bundle's job. SDK 2.x was written against Couchbase Server 4.x/5.x. Behaviour against 6.x and 7.x varies, particularly around authentication and bucket types. Check the libcouchbase version your extension is linked against, not just the extension version.

No ODM, no migrations, no schema. Design documents (views, indexes) must be managed out-of-band — a bin/console command you write, a deploy step, or manual creation. The bundle provides nothing for this. Plan for it early or you'll find N1QL queries silently failing on a fresh environment because the required GSI index was never created.

Configuration is compiled into the container. Changing couchbase: config requires a cache clear. If you're hot-swapping credentials via env vars, verify the container isn't caching values from a previous boot (bin/console cache:clear).

Read the source before relying on behaviour. With 4 stars and a description that literally says "just basic stuff in the first place", expect gaps and zero hand-holding. The whole bundle is small enough to read in an hour. Pay attention to: which SDK classes it references (tell-tale sign of 2.x vs 3.x), how it handles bucket passwords vs cluster credentials, and whether it registers aliases for autowiring.

Extension points are essentially "override the service". There is no plugin system. If you need custom behaviour (profiling, key hashing, encryption-at-rest), the cleanest path is to define your own services and either consume the bundle's cluster service or bypass the bundle entirely with a hand-rolled CouchbaseCluster factory. Don't expect upstream changes — the maintenance signal here is very weak.

Upgrade path is a rewrite, not a bump. If you ever need to move to SDK 3.x, you'll replace the bundle and rewrite every call site (get/upsert/N1QL APIs all changed shape). Keep your CouchbaseBucket usage confined to a thin repository layer from day one — that's the single decision that makes this bundle tolerable.