{"id":15739993,"url":"https://github.com/ace411/couchdb_ext","last_synced_at":"2025-03-13T08:31:48.572Z","repository":{"id":37631850,"uuid":"172651021","full_name":"ace411/couchdb_ext","owner":"ace411","description":"A PHP extension for CouchDB","archived":false,"fork":false,"pushed_at":"2022-06-28T19:22:34.000Z","size":297,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-26T19:27:26.782Z","etag":null,"topics":["apache-couchdb","c","couchdb","couchdb-client","couchdb-php","couchdb-phpextension","database","php","php-extension","php-extensions"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ace411.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-26T06:24:13.000Z","updated_at":"2024-05-25T02:53:17.000Z","dependencies_parsed_at":"2022-08-18T03:05:48.235Z","dependency_job_id":null,"html_url":"https://github.com/ace411/couchdb_ext","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace411%2Fcouchdb_ext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace411%2Fcouchdb_ext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace411%2Fcouchdb_ext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace411%2Fcouchdb_ext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ace411","download_url":"https://codeload.github.com/ace411/couchdb_ext/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243369870,"owners_count":20280091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache-couchdb","c","couchdb","couchdb-client","couchdb-php","couchdb-phpextension","database","php","php-extension","php-extensions"],"created_at":"2024-10-04T02:10:31.100Z","updated_at":"2025-03-13T08:31:48.238Z","avatar_url":"https://github.com/ace411.png","language":"C","readme":"# php-couchdb\n\nA simple PHP extension for CouchDB.\n\n## Requirements\n\n- libcurl\n\n- PHP 8 or newer\n\n- async.h\n\n## Installation\n\nBecause couchdb is an extension built on top of libcurl, installation of said utility is a mandatory prerequisite for using this tool.\n\nInstalling libcurl can be done by typing the following in a console of your choosing.\n\n```sh\n$ sudo apt-get install libcurl4-openssl-dev\n```\n\n### Enabling asynchronous transactions\n\nThe asynchrony in the couchdb extension - that powers its transaction feature - is a caller-based fork-join model. Considering `couchdb` cannot work without [async.h](https://github.com/naasking/async.h), you will have to install the library in any one of several possible global include directories (`/usr/include`, `/usr/local/include`, `/usr/local/opt/include`).\n\nYou can install the said library - by executing the `async.sh` shell script in this project's root directory - by typing the following.\n\n```sh\n$ chmod a+x async.sh\n$ ./async.sh\n```\n\nIf you have downloaded the library yourself, you can supply the path to the library directory - directly to the `async.sh` script - as a command line argument.\n\n```sh\n$ ./async.sh path/to/async.h\n```\n\nUpon successfully installing each of the aforedescribed dependencies, proceed to type the following to install `couchdb`.\n\n```sh\n$ phpize\n$ ./configure --enable-couchdb --with-curl=\"/path/to/libcurl\"\n$ make \u0026\u0026 sudo make install\n```\n\n\u003e Remember to add the `couchdb` shared object file (`extension=couchdb`) to your `php.ini` file to operationalize the extension.\n\nIf you intend to run the tests, the following should suffice.\n\n```sh\n$ make test\n```\n\n## Basic Usage\n\nThe snippet below demonstrates how to configure CouchDB for local installations, determine if the service is available - and subsequently generate five Universally Unique Identifiers (UUIDs).\n\n```php\n$basic = CouchDb::connect();\n\nif (!$basic-\u003eisAvailable()) {\n  exit();\n}\n\necho $basic-\u003euuids(5);\n```\n\n## API Reference\n\n```php\nclass CouchDb\n{\n  /* Constants */\n  public const RETURN_ARRAY;\n  public const RETURN_JSON;\n\n  /* Methods */\n  public static connect( array $config ) : CouchDb;\n  public session() : CouchDb;\n  public isAvailable() : bool;\n  public uuids( int $count ) : string|array;\n  public databases() : string|array;\n  public database( string $database ) : string|array;\n  public createDatabase( string $database ) : bool;\n  public deleteDatabase( string $database ) : bool;\n  public insertDocuments( string $database [, array $documents ] ) : bool;\n  public document( string $database [, string $documentId ] ) : string|array;\n  public documents( string $database [, array $keys = null ] ) : string|array;\n  public updateDocuments( string $database [, array $documents ] ) : bool;\n  public deleteDocuments( string $database [, array $documents ] ) : bool;\n  public find( string $database [, array $query ] ) : string|array;\n  public createIndex( string $database [, array $options ] ) : bool;\n  public createDesignDocument( string $database [, string $designDocument [, array $options ]] ) : bool;\n  public view( string $database [, string $designDocument [, string $view [, array $options ]]] ) : string|array;\n  public changes( string $database [, array $options = null ] ) : bool;\n  public transaction( array $transactions ) : array;\n}\n```\n\n### connect\n\nParametrically instantiates the CouchDb class.\n\n```php\npublic CouchDb::connect(array $config);\n```\n\nEstablishes the parameters for [Basic Auth-enabled](https://docs.couchdb.org/en/stable/api/server/authn.html#basic-authentication) CouchDB interactions.\n\n#### Parameters\n\n- **config** (array) - List of configuration options\n  - **host** (string) - Base URI for CouchDB interactions\n  - **user** (string) - Arbitrary CouchDB username\n  - **pass** (string) - Arbitrary CouchDB password\n  - **port** (string) - CouchDB port\n  - **timeout** (string) - Timeout for requests made to CouchDB server\n  - **type** (integer) - Return type for request data\n\n```php\n// default parameters\n$basic = CouchDb::connect(\n  [\n    'host'    =\u003e 'http://127.0.0.1',\n    'user'    =\u003e '',\n    'pass'    =\u003e '',\n    'token'   =\u003e '',\n    'port'    =\u003e 5984,\n    'timeout' =\u003e 60,\n    'type'    =\u003e CouchDb::RETURN_JSON,\n  ],\n);\n```\n\n### session\n\nRetrieves auth token from CouchDB.\n\n```php\npublic CouchDb::session();\n```\n\nThis method effectively exchanges the `user` and `password` information specified in class instantiation for an [auth token](https://docs.couchdb.org/en/stable/api/server/authn.html#cookie-authentication) and thence places the said token in the CouchDb object's parameterized state. It jettisons previously assigned `user` and `password` information.\n\n\u003e `session` persists all non-credential configuration from a previous `connect` call and is an [**opt-in** feature](https://).\n\n#### Parameters\n\n\u003e None\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n    'type' =\u003e CouchDb::RETURN_ARRAY,\n  ],\n);\n\n$session = $basic-\u003esession();\n```\n\n### available\n\nChecks if a CouchDB instance is available the specified address.\n\n```php\npublic CouchDb::available();\n```\n\n#### Parameters\n\n\u003e None\n\n```php\n$basic = CouchDb::connect();\n\nif ($basic-\u003eavailable()) {\n  echo 'Up and running!' . PHP_EOL;\n}\n```\n\n### uuids\n\nRetrieves, from CouchDB, a specified number of Universally Unique Identifiers (UUIDs).\n\n```php\npublic CouchDb::uuids(int $count);\n```\n\n#### Parameters\n\n- **count** (integer) - The number of UUIDs to generate\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\necho $basic-\u003euuids(2);\n```\n\n### createDatabase\n\nCreates a new database.\n\n```php\npublic CouchDb::createDatabase(string $database);\n```\n\n#### Parameters\n\n- **database** (string) - The name of the database to create\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\nif ($basic-\u003ecreateDatabase('recipes')) {\n  echo 'Database created' . PHP_EOL;\n}\n```\n\n### databases\n\nReturns a list containing the names of all the databases available to a user.\n\n```php\npublic CouchDb::databases();\n```\n\n#### Parameters\n\n\u003e None\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\necho $basic-\u003edatabases();\n```\n\n### database\n\nRetrieves information about a specified database.\n\n```php\npublic CouchDb::database(string $database);\n```\n\n### Parameters\n\n- **database** (string) - The name of the database the information about which you intend to retrieve\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\necho $basic-\u003edatabase('recipes');\n```\n\n### deleteDatabase\n\nDeletes a specified database.\n\n```php\npublic CouchDb::deleteDatabase(string $database);\n```\n\n#### Parameters\n\n- **database** (string) - The database you intend to delete\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\n$session = $basic-\u003esession();\n\nif ($session-\u003edeleteDatabase('vehicles')) {\n  echo 'Successfully purged!' . PHP_EOL;\n}\n```\n\n### document\n\nRetrieves the contents of a specified document.\n\n```php\npublic CouchDb::document(string $database, string $documentId);\n```\n\n#### Parameters\n\n- **database** (string) - The database from which to retrieve the document\n- **documentId** (string) - The unique identifier (`_id`) of the document whose information is to be retrieved\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n    'type' =\u003e CouchDb::RETURN_ARRAY,\n  ],\n);\n\n$session = $basic-\u003esession();\n\necho $session-\u003edocument('recipes', 'BeefStew');\n```\n\n### documents\n\nRetrieves several documents in a single call.\n\n```php\npublic CouchDb::documents(string $database, array $keys = null);\n```\n\nThe method retrieves all documents in a specified database if a set of keys is not specified.\n\n#### Parameters\n\n- **database** (string) - The database from which you intend to retrieve a set of documents\n- **keys** (array) - A list of document identifiers with which to tune the server response\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\necho $basic-\u003edocuments('recipes', ['FishStew', 'LambStew']);\n```\n\n### insertDocuments\n\nCreates multiple documents.\n\n```php\npublic CouchDb::insertDocuments(string $database, array $documents);\n```\n\n#### Parameters\n\n- **database** (string) - The database in which to insert documents\n- **documents** (array) - The document data to insert into a specified database\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\n$session = $basic-\u003esession();\n\nif (\n  $session-\u003einsertDocuments(\n    'recipes',\n    [\n      [\n        '_id'       =\u003e 'FishStew',\n        'subtitle'  =\u003e 'Delicious with freshly baked bread',\n      ],\n      [\n        '_id'       =\u003e 'LambStew',\n        'subtitle'  =\u003e 'Serve with a whole meal scone topping',\n      ],\n    ],\n  )\n) {\n  echo 'Documents successfully created!' . PHP_EOL;\n}\n```\n\n### updateDocuments\n\nUpdates multiple documents.\n\n```php\npublic updateDocuments(string $database, array $documents);\n```\n\n#### Parameters\n\n- **database** (string) - The database whose documents you intend to modify\n- **documents** (array) - The list of contents, inclusive of `_id` and `_rev` keys with which to update entries in a database\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\nif (\n  $basic-\u003eupdateDocuments(\n    'recipes',\n    [\n      [\n        '_id'       =\u003e 'FishStew',\n        '_rev'      =\u003e '1-41669894c7d25a634f5de4fef75fb982',\n        'servings'  =\u003e 4,\n      ],\n      [\n        '_id'       =\u003e 'LambStew',\n        '_rev'      =\u003e '1-599acfa0c7b36889599bde56276e444c',\n        'servings'  =\u003e 6,\n      ],\n    ],\n  )\n) {\n  echo 'Database successfully updated!' . PHP_EOL;\n}\n```\n\n### deleteDocuments\n\nDeletes multiple documents.\n\n```php\npublic deleteDocuments(string $database, array $documents);\n```\n\n#### Parameters\n\n- **database** (string) - The database whose documents you intend to delete\n- **documents** (array) - The list containing `_id` and `_rev` keys of the documents you intend to delete\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\n$session = $basic-\u003esession();\n\nif (\n  $session-\u003edeleteDocuments(\n    'recipes',\n    [\n      [\n        '_id'   =\u003e 'Pilau',\n        '_rev'  =\u003e '1-599acfa0c7b36889599bde56276e444c',\n      ],\n      [\n        '_id'   =\u003e 'Katogo',\n        '_rev'  =\u003e '1-41669894c7d25a634f5de4fef75fb982',\n      ],\n    ],\n  )\n) {\n  echo 'Documents successfully deleted!' . PHP_EOL;\n}\n```\n\n### find\n\nPerforms a parameterized Mango Query-powered database search.\n\n```php\npublic CouchDb::find(string $database, array $query);\n```\n\n#### Parameters\n\n- **database** (string) - The database on which you intend to perform the search\n- **query** (array) - The database query parameters\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n    'type' =\u003e CouchDb::RETURN_ARRAY,\n  ],\n);\n\necho $basic-\u003efind(\n  'recipes',\n  [\n    'execution_stats' =\u003e false,\n    'fields'          =\u003e ['_id', 'servings'],\n    'selector'        =\u003e [\n      '_id'           =\u003e ['$regex' =\u003e '(?i)eef'],\n    ],\n  ],\n);\n```\n\n### createIndex\n\nCreates a CouchDB index for a specified database.\n\n```php\npublic CouchDb::createIndex(string $database, array $options);\n```\n\n#### Parameters\n\n- **database** (string) - The database on which to define the index\n- **options** (array) - The list of options with which to configure the index\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\n$session = $basic-\u003esession();\n\nif (\n  $session-\u003ecreateIndex(\n    'recipes',\n    [\n      'ddoc'      =\u003e 'servings-index',\n      'type'      =\u003e 'json',\n      'index'     =\u003e [\n        'fields'  =\u003e ['_id', 'servings', 'subtitle'],\n      ],\n    ],\n  )\n) {\n  echo 'Index successfully created!' . PHP_EOL;\n}\n```\n\n### createDesignDocument\n\nCreates a design document in a specified database.\n\n```php\npublic CouchDb::createDesignDocument(\n  string $database,\n  string $designDocument,\n  array $options\n);\n```\n\nThis method is especially useful for creating views the display parameters for which can be tuned via CouchDB map-reduce functions.\n\n#### Parameters\n\n- **database** (string) - The database in which to create the design document\n- **designDocument** (string) - The name of the design document\n- **options** (array) - The list of options with which to configure the design document\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\nif (\n  $basic-\u003ecreateDesignDocument(\n    'recipes',\n    'recipesDoc',\n    [\n      'language'  =\u003e 'javascript',\n      'views'     =\u003e [\n        'servings-view' =\u003e [\n          'map' =\u003e 'function (doc) { emit(doc._id, doc.servings) }'\n        ],\n      ],\n    ],\n  )\n) {\n  echo 'Successfully created design document' . PHP_EOL;\n}\n```\n\n### view\n\nQueries a view and retrieves all the records it is configured to project.\n\n```php\npublic CouchDb::view(\n  string $database,\n  string $designDocument,\n  string $view\n  array $options = null\n);\n```\n\n#### Parameters\n\n- **database** (string) - The database the data in which the view projects\n- **designDocument** (string) - The identifier of the design document\n- **view** (string) - The name of the view\n- **options** (array) - Additional non-mandatory query options\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'admin',\n    'pass' =\u003e 'root',\n  ],\n);\n\n$session = $basic-\u003esession();\n\necho $basic-\u003eview(\n  'recipes',\n  'recipesDoc',\n  'servings-view',\n  [\n    'descending'  =\u003e true,\n    'conflicts'   =\u003e false,\n    'update'      =\u003e true,\n  ],\n);\n```\n\n### changes\n\nRetrieves a history of all actions performed on a database.\n\n```php\npublic CouchDb::changes(string $database, array $options = null);\n```\n\n#### Parameters\n\n- **database** (string) - The database whose history you intend to track\n- **options** (array) - A list of options with which to tune the CouchDB response\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n  ],\n);\n\necho $basic-\u003echanges(\n  'recipes',\n  [\n    'conflicts'     =\u003e true,\n    'include_docs'  =\u003e true,\n    'descending'    =\u003e true,\n  ],\n);\n```\n\n### transaction\n\nConcurrently executes multiple CouchDB actions in a fashion akin to transactions in SQL.\n\n```php\npublic CouchDb::transaction(array $actions);\n```\n\nThis function throws an exception in situations where the requisite protothreads library is not installed.\n\n#### Parameters\n\n- **actions** (array) - A list of PHP functions in which to subsume extension-supported CouchDB operations\n\n```php\n$basic = CouchDb::connect(\n  [\n    'user' =\u003e 'root',\n    'pass' =\u003e 'admin',\n    'type' =\u003e CouchDb::RETURN_ARRAY,\n  ],\n);\n\n$session = $basic-\u003esession();\n\nprint_r(\n  $session-\u003etransaction(\n    [\n      // create a database\n      fn () =\u003e $session-\u003edatabase('recipes'),\n      // insert documents in database\n      fn () =\u003e\n        $session-\u003einsertDocuments(\n          'recipes',\n          [\n            [\n              '_id'       =\u003e 'FishStew',\n              'servings'  =\u003e 4,\n              'subtitle'  =\u003e 'Delicious with freshly baked bread',\n            ],\n            [\n              '_id'       =\u003e 'LambStew',\n              'servings'  =\u003e 6,\n              'subtitle'  =\u003e 'Serve with a whole meal scone topping',\n            ],\n          ],\n        ),\n      // create index\n      fn () =\u003e\n        $session-\u003ecreateIndex(\n          'recipes',\n          [\n            'ddoc'      =\u003e 'servings-index',\n            'type'      =\u003e 'json',\n            'index'     =\u003e [\n              'fields'  =\u003e ['servings', 'subtitle'],\n            ],\n          ],\n        ),\n      // create design document\n      fn () =\u003e\n        $session-\u003ecreateDesignDocument(\n          'recipes',\n          'recipesDoc',\n          [\n            'language'  =\u003e 'javascript',\n            'views'     =\u003e [\n              'servings-view' =\u003e [\n                'map' =\u003e 'function (doc) { emit(doc._id, doc.servings) }'\n              ],\n            ],\n          ],\n        ),\n    ],\n  ),\n);\n```\n\n## Dealing with problems\n\nEndeavor to create an issue on GitHub when the need arises or send an email to lochbm@gmail.com\n\n## Contributing\n\nConsider buying me a coffee if you appreciate the offerings of the project and/or would like to provide more impetus for me to continue working on it.\n\n# \u003ca href=\"https://www.buymeacoffee.com/agiroLoki\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/lato-white.png\" alt=\"Buy Me A Coffee\" style=\"height: 51px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n","funding_links":["https://www.buymeacoffee.com/agiroLoki"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Face411%2Fcouchdb_ext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Face411%2Fcouchdb_ext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Face411%2Fcouchdb_ext/lists"}