Couchdb Laravel Package

Getting Started

Begin by installing via Composer (composer require doctrine/couchdb:@dev) and instantiate a client using CouchDBClient::create(['dbname' => 'your_db']). The README’s basic CRUD section provides the fastest path to first use: create a database, post a document, fetch it. Always verify your CouchDB version — this package only supports CouchDB 2.x (no 3.x). For legacy 1.x deployments, use the archived release/1.0.0 branch.

Implementation Patterns

• Document lifecycle: Use postDocument() for inserts (auto-generates ID/rev), putDocument() for updates (must pass _id + current _rev), and deleteDocument() with correct revision to avoid 409s. Bulk operations (postDocuments, putDocuments) dramatically improve throughput for seed data or ETL jobs.
• View management: Define MapReduce views via classes implementing View\DesignDocument. Deploy them once via createDesignDocument() (idempotent in practice). Queries use createViewQuery() — chain setKey(), setReduce(true), setIncludeDocs(true) as needed. Design doc names should match your domain (e.g., 'users', 'orders').
• Mango querying: For modern apps on CouchDB ≥2.0, use MangoQuery with selector arrays (e.g., ['_id' => ['$gt' => null]]) and options for sorting, pagination, and index hints (use_index). Ensure CouchDB has appropriate indexes (_index endpoint) — otherwise queries fall back to full scan.
• Changes feed: Use getChanges(['since' => 'now']) for real-time sync jobs. Persist last_seq externally (e.g., database or file) to resume after restarts.

Gotchas and Tips

• Revision hell: Document updates require the latest _rev. Conflicts (409) are common when reusing stale revs. Wrap putDocument() in a loop: catch exception, refetch rev, retry. Consider findDocument() before critical updates.
• Archived & insecure: No updates since 2015. Critical security gaps (e.g., HTTP client, JSON parsing) go unpatched. Never use in new projects. If unavoidable in legacy systems, isolate access (firewall, limited DB user) and monitor for anomalies.
• JSON encoding pitfalls: Query params like key, startkey, endkey must be JSON-encoded strings, but older versions may double-encode or escape incorrectly. If view queries return 400 Bad Request, inspect raw HTTP requests (use StreamClient with logging) or force JSON encoding via client config: ['json_encode_flags' => JSON_UNESCAPED_SLASHES].
• No PSR compliance: The client uses custom HTTP interfaces — cannot plug into modern PSR-18/Guzzle middleware stacks. Extend CouchDBClient to inject a PSR-18 client, or use a fork.
• CouchDB version mismatch: This client breaks with CouchDB 3.x due to removed APIs (e.g., legacy auth, _all_docs behavior, Mango syntax changes). Verify your target CouchDB version before integrating — /_db health check is critical.