Weave Code
Laravel Couchbase Laravel Package
friendsofcat/laravel-couchbase
Laravel Couchbase integrates Couchbase into Laravel with a query builder, Eloquent-style models, and cache/session drivers, making it easy to use Couchbase as a fast NoSQL backend for documents, caching, and scalable Laravel applications.
A Laravel friendly service for interacting with Couchbase
Frequently asked questions about Laravel Couchbase
- How do I install friendsofcat/laravel-couchbase in a Laravel app?
- Install it with composer require friendsofcat/laravel-couchbase. You must also install the PECL couchbase extension and a compatible Couchbase PHP SDK, because Composer alone is not enough. The service provider is auto-discovered, and you publish the package config to set your connection details.
- Does laravel-couchbase work with Laravel 11 and Laravel 12?
- The last release is from May 2023, which puts it in the Laravel 9/10 and PHP 8.1/8.2 era. There is no published CI matrix proving Laravel 11 or 12 support, so verify against your target versions before committing. A short spike on your PHP, Laravel and Couchbase Server versions is the safe path.
- Do I need the Couchbase PHP SDK or PECL extension to use this package?
- Yes. The package sits on top of the Couchbase PHP SDK, which is a native PECL extension rather than a pure Composer dependency. That means your runtime image must compile or install the extension, which is easy on Docker images you control and often blocked on managed PaaS. It also affects Alpine/musl and arm64 builds.
- Can I use Eloquent relationships and auto-increment IDs with Couchbase?
- No. Couchbase is a JSON document store where key-value access is primary and N1QL is the query layer; it does not provide Eloquent relationships, auto-increment keys or cross-document joins. The package offers Eloquent-style models as a convenience, but planning around ORM semantics will fight both the package and the datastore. Model documents by access pattern and key design instead.
- How do I configure the Couchbase connection in Laravel?
- Publish the package config and set your connection, bucket and credentials through environment variables. The provider binds a cluster and bucket instance into the Laravel container, and the facade resolves that binding so call sites stay short. Check whether the binding is a singleton if you run long-lived workers.
- Is laravel-couchbase safe with Laravel Octane and queue workers?
- There is no documented guarantee in the README, so treat connection lifetime as something to verify yourself. If the cluster or bucket is bound as a singleton, long-running Octane workers and queue consumers can hold stale connections after restarts. Test reconnection behaviour under Octane and worker restarts, and consider resolving connections per job if needed.
- How can I test a Laravel app that uses Couchbase in CI?
- There is no built-in fake or in-memory Couchbase double described, so CI pipelines typically need a live Couchbase container. That adds startup time and flakiness compared with SQLite or Redis fakes. Wrapping Couchbase calls behind your own repository interface lets you fake at that boundary and keeps the package replaceable.
- What are the alternatives to laravel-couchbase for using Couchbase with Laravel?
- The main alternative is using the official Couchbase PHP SDK directly, which removes a thin, lightly maintained wrapper from your dependency graph. There is no first-party Laravel Couchbase integration, and community packages in this space are few. Keeping Couchbase behind an internal repository interface makes switching between this package, direct SDK calls, or a fork straightforward.
- Is friendsofcat/laravel-couchbase actively maintained?
- The repository has around 14 stars and its last release dates to May 2023, suggesting a single maintainer and little issue traffic. It is MIT licensed, so you can fork and patch it if needed. For production, budget for either a support arrangement or the ability to swap to direct SDK calls.
- When should I use Couchbase instead of MySQL or Redis in a Laravel app?
- Use it when your access pattern is fetch or put a document by key, or a bounded N1QL query, such as user profiles, catalogs, entitlements or feature flags. It is a poor fit for relational domains that depend on joins, cross-document transactions or auto-increment IDs. Adopt it because Couchbase is already a sanctioned datastore, not because this package makes it convenient.
Weaver
How can I help you explore Laravel packages today?