Rug Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer (if still functional):

   composer require o100ja/rug
   

   Note: Due to the last release being from 2013, verify compatibility with your PHP/CouchDB versions.

2. Basic Setup Initialize the client in a Laravel service provider (e.g., AppServiceProvider):

   use Rug\Client;
   
   public function register()
   {
       $this->app->singleton('couchdb', function ($app) {
           return new Client('http://localhost:5984');
       });
   }
   

3. First Use Case Connect to a CouchDB database and fetch a document:

   $couch = app('couchdb');
   $db = $couch->db('mydb');
   $doc = $db->get('doc_id');
   

Where to Look First

• README.md: For basic usage (though sparse).
• Source Code: Explore src/Rug/Client.php and src/Rug/Database.php for API structure.
• CouchDB HTTP API Docs: Official CouchDB REST API for reference.

Implementation Patterns

Core Workflows

1. Database Operations

   • Create/Update/Delete:

     $db->save($document); // Upsert
     $db->delete('doc_id');
     

   • Bulk Operations:

     $db->bulk($documents); // Array of docs
     

2. Querying

   • Views (MapReduce):

     $result = $db->view('design_doc', 'view_name', ['key' => 'value']);
     

   • Simple Queries:

     $docs = $db->find(['selector' => ['field' => 'value']]); // Mango Query (if supported)
     

3. Authentication

   • Pass credentials during client initialization:

     new Client('http://localhost:5984', 'user', 'pass');
     

4. Event Handling

   • Listen for changes (if supported):

     $db->changes(function ($change) {
         // Handle change
     });
     

Integration Tips

• Laravel Service Container: Bind the client to the container for dependency injection.
• Configuration: Store CouchDB credentials in .env:

  COUCHDB_URL=http://localhost:5984
  COUCHDB_USER=user
  COUCHDB_PASS=pass
  

  Then inject via:

  new Client(config('couchdb.url'), config('couchdb.user'), config('couchdb.pass'));
  

• Error Handling: Wrap operations in try-catch:

  try {
      $doc = $db->get('doc_id');
  } catch (\Rug\Exception $e) {
      Log::error($e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Deprecation Risk

   • The package is abandoned (last release: 2013). Use at your own risk.
   • Mitigation: Fork the repo and update dependencies (e.g., Guzzle HTTP client).

2. Outdated Features

   • May lack support for modern CouchDB features (e.g., Mango Queries, PouchDB sync).
   • Workaround: Fall back to raw HTTP requests for unsupported features.

3. No Laravel-Specific Features

   • No Eloquent integration, query builder, or caching layers.
   • Tip: Build a facade or repository pattern to abstract CouchDB logic.

4. Authentication Issues

   • Basic auth may not work with modern CouchDB setups (e.g., cookie auth).
   • Fix: Use the COUCHDB_COOKIE environment variable or raw HTTP headers.

5. No Type Safety

   • Responses are raw arrays. Validate data manually:

     $doc = $db->get('doc_id');
     if (!isset($doc['_id'])) throw new \RuntimeException('Invalid document');
     

Debugging Tips

• Enable Debugging:

  $client = new Client('http://localhost:5984', null, null, [
      'debug' => true,
  ]);
  

• Check Raw Responses:

  $response = $db->get('doc_id', ['raw' => true]);
  

• Log Requests: Use a Guzzle middleware or Laravel’s logging:

  $client->getHttpClient()->getEmitter()->attach(
      new \GuzzleHttp\Middleware::tap(function ($request) {
          Log::debug('CouchDB Request:', ['url' => (string) $request->getUri()]);
      })
  );
  

Extension Points

1. Custom HTTP Client Override the default client (e.g., for retries or timeouts):

   $client = new Client('http://localhost:5984', null, null, [
       'http_client' => new \GuzzleHttp\Client(['timeout' => 30]),
   ]);
   

2. Event Dispatching Extend the client to dispatch Laravel events:

   $db->save($doc);
   event(new CouchDBDocumentSaved($doc));
   

3. Query Builder Create a fluent interface for complex queries:

   $query = (new CouchDBQuery($db))
       ->where('type', 'user')
       ->limit(10);
   $results = $query->get();
   

4. Caching Layer Cache frequent queries using Laravel’s cache:

   $cacheKey = "couchdb:view:{$designDoc}:{$viewName}:".md5($options);
   return Cache::remember($cacheKey, 60, function () use ($db, $designDoc, $viewName, $options) {
       return $db->view($designDoc, $viewName, $options);
   });