Getting Started

Before you install, verify compatibility. This package has a single star and no dependents, so treat it as unvetted code rather than a maintained integration. Open the composer.json in the repo and check the require block for the Laravel version constraint and which Couchbase SDK it wraps (couchbase/couchbase PHP extension vs. the pure-PHP couchbase SDK). That single check determines whether the rest of this guide applies to your stack.

Minimal install:

composer require developermarshak/laravel-couchbase

Then, in order:

Publish the config — php artisan vendor:publish --provider="DeveloperMarshak\Couchbase\CouchbaseServiceProvider" (confirm the provider namespace by reading src/ — with a package this small the README may not match the code).
Register the provider manually in config/app.php if it predates Laravel package auto-discovery (check extra.laravel.providers in its composer.json).
Add a connection to config/database.php:

'couchbase' => [
    'driver'   => 'couchbase',
    'host'     => env('COUCHBASE_HOST', '127.0.0.1'),
    'port'     => env('COUCHBASE_PORT', 8091),
    'username' => env('COUCHBASE_USERNAME'),
    'password' => env('COUCHBASE_PASSWORD'),
    'bucket'   => env('COUCHBASE_BUCKET'),
],

Smoke-test in tinker before writing any application code:

DB::connection('couchbase')->getBucket()->upsert('test::1', ['hello' => 'world']);
DB::connection('couchbase')->getBucket()->get('test::1');

Where to look first: src/ — specifically the service provider, the connection class (does it extend Illuminate\Database\Connection?), and any query grammar. Those three files tell you what the package actually supports versus what the README claims. The config file is the second stop; it usually reveals defaults for timeouts, consistency, and whether collections/scopes are wired up.

First real use case: pick the narrowest one. A key-value lookup for a settings or profile document is the safe entry point. Do not start by swapping your Eloquent models over — that's where thin Couchbase integrations break first.

Implementation Patterns

Key-value access is the happy path. Couchbase's KV operations are the fastest and least ambiguous part of any Laravel wrapper. Expose the bucket through a small repository rather than letting controllers touch the SDK:

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

    public function find(string $id): ?array
    {
        try {
            return $this->bucket->get("profile::{$id}")->content;
        } catch (DocumentNotFoundException) {
            return null;
        }
    }

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

Bind the bucket in a service provider so the rest of the app never imports the SDK directly. This is also your seam for testing.

N1QL through the query builder. If the package registers a grammar, DB::connection('couchbase')->select(...) should accept raw N1QL with bindings:

DB::connection('couchbase')->select(
    'SELECT META(p).id AS id, p.* FROM `profiles` p WHERE p.status = $status LIMIT $limit',
    ['status' => 'active', 'limit' => 50]
);

If the builder is incomplete, drop to ->getCluster()->query(...) on the underlying SDK — but wrap it, because you're now depending on an internal accessor that could vanish. Prefer named parameters ($name) over positional; they survive query edits.

Eloquent, with caution. Treat Eloquent as a convenience layer, not a guarantee:

class Profile extends Model
{
    protected $connection = 'couchbase';
    protected $primaryKey = 'id';
    public $incrementing = false;
    protected $keyType = 'string';
    protected $casts = ['preferences' => 'array'];
}

Override getKeyName() if the package maps document IDs via META().id rather than a field. Nested objects should go through $casts so you get arrays back instead of stdClass. Anything involving save() on an existing document, updateOrCreate, or soft deletes needs an explicit test — those paths rely on grammar methods a small package may stub out.

Multiple buckets or scopes. Define one Laravel connection per bucket (couchbase, couchbase_audit, etc.) and pass ->connection('couchbase_audit') explicitly. Don't try to switch buckets at runtime on a shared connection; SDK connections are bound to a bucket at construction.

Integrations worth checking. If your app uses cache or sessions, look for a Couchbase cache driver or session handler in the package before wiring one yourself — KV is a natural fit and the payoff (removing Redis) is real. If it's absent, a custom CacheStore is ~40 lines.

Testing. There's no SQLite equivalent. Two options: point tests at a disposable test bucket (fast, requires a running cluster in CI), or fake at the repository interface. Default to the latter for unit tests and reserve the real bucket for a thin integration suite.

Gotchas and Tips

The package itself is the biggest gotcha. One star, zero dependents, no release history means no one is finding the bugs before you. Before committing: read every line of src/ (it's small), pin an exact version in composer.json, and vendor it into a private fork if you ship it. Pay particular attention to how credentials are handled — a naive implementation may log passwords or bypass RBAC.

"No index available" is the error you will hit first. N1QL requires a primary index per bucket. Create it once from the admin UI or cbq:

CREATE PRIMARY INDEX ON `profiles`;

For scopes/collections, the syntax is CREATE PRIMARY INDEX ON \bucket`.`scope`.`collection`;` — and the query must be run in that scope context or it silently targets the default.

Consistency is eventual. After a write, a subsequent N1QL query may not see it. Ask for RequestPlus scan consistency if correctness beats latency:

$opts = new QueryOptions();
$opts->scanConsistency(QueryScanConsistency::REQUEST_PLUS);

KV reads by key are strongly consistent by default — another reason to prefer them.

Transactions don't work like Laravel expects. DB::transaction() on this connection will either throw or silently no-op. Couchbase's distributed ACID transactions are a separate SDK API with their own callback shape. Don't assume rollback semantics; restructure the operation or use the SDK's transaction function directly.

Connection lifecycle and Octane. Couchbase connections are long-lived and pool internally. Confirm the service provider registers the connection as a singleton. Under Octane, a connection created before a worker boot may hold stale state; test a worker restart path.

config:cache bites. If the package's config file calls env() at the top level rather than inside the returned array, cached config will bake in the values from the caching machine. Check the file and move env() calls inside the array if needed.

Debugging. Enable SDK logging (couchbase.log or ->setLogger() on the cluster) and confirm the failing call is even reaching the cluster. For N1QL, copy the generated statement into cbq — if it fails there, it's your query, not the package. For KV, watch the Couchbase server logs for rejected auth or missing bucket permissions, which surface in Laravel as generic connection exceptions.

Extension points. The cleanest places to customize are: a custom Connector subclass if credentials/host resolution needs work, DB::connection('couchbase')->macro(...) or a QueryBuilder subclass for reusable queries, and a repository/decorator layer over the bucket for everything else. Do not patch vendor/ — fork instead, given the maintenance risk.

Watch timeouts explicitly. Thin packages often inherit the SDK default of 2.5s for KV and 75s for queries. Set operation and query timeouts in the connection config, and distinguish connect timeouts from read timeouts when tuning — a slow index build looks identical to a down cluster from the application's side.

Laravel Couchbase Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips