1# Couchbase PHP Client [![Build Status](http://sdkbuilds.sc.couchbase.com/buildStatus/icon?job=builds-php)](http://sdkbuilds.sc.couchbase.com/job/builds-php)
2
3This library allows you to connect to a Couchbase cluster from PHP.
4It is a native PHP extension and uses the very fast libcouchbase library to
5handle communicating to the cluster over the Couchbase binary protocol.
6It supports 5.x and 7.x releases of PHP interpreter.
7
8## Useful Links
9
10* Source - https://github.com/couchbaselabs/php-couchbase
11* Bug Tracker - https://www.couchbase.com/issues/browse/PCBC
12* Couchbase PHP Community - https://forums.couchbase.com/c/php-sdk
13* Documentation - https://developer.couchbase.com/documentation/server/current/sdk/php/start-using-sdk.html
14* PECL - https://pecl.php.net/package/couchbase
15* Packages - https://developer.couchbase.com/server/other-products/release-notes-archives/php-sdk
16* Snapshots - http://sdkbuilds.sc.couchbase.com/job/php-sdk-package/lastSuccessfulBuild/artifact/packages/
17
18
19## Installing
20
21The target system should have libcouchbase installed. Detailed guide and links to the most recent versions
22located here: https://developer.couchbase.com/server/other-products/release-notes-archives/c-sdk.
23
24### PECL
25
26Couchbase PHP client generally available through PECL: http://pecl.php.net/package/couchbase
27
28```bash
29pecl install couchbase
30```
31
32### Binary packages
33
34RPM package for Fedora available in official repository, its name is [php-pecl-couchbase2](https://apps.fedoraproject.org/packages/php-pecl-couchbase2).
35
36```bash
37dnf install php-pecl-couchbase2
38```
39
40RPM package for RHEL and CentOS linux available on [Remi's repository](https://rpms.remirepo.net/).
41
42```bash
43yum install php-pecl-couchbase2
44```
45
46Additionally Windows builds available from [Release Notes and Archives](http://developer.couchbase.com/server/other-products/release-notes-archives/php-sdk) page.
47
48On MacOS platform, the library could be installed via Homebrew:
49
50```bash
51brew tap homebrew/homebrew-php
52brew install php70-couchbase # or other version instead of 70 (PHP 7.0)
53```
54
55### Build from sources
56
57If you are going to prepare patches, or just need to install the most recent
58version from git, make sure you have PHP development tools and headers
59installed, and run the following commands:
60
61```bash
62git clone git://github.com/couchbase/php-couchbase.git
63cd php-couchbase
64phpize
65./configure --with-couchbase
66make && make install
67```
68
69## Introduction
70
71Connecting to a Couchbase bucket is as simple as creating a new Connection
72instance.  Once you are connect, you may execute any of Couchbases' numerous
73operations against this connection.
74
75Here is a simple example of instantiating a connection, setting a new document
76into the bucket and then retrieving its contents:
77
78```php
79$cluster = new \Couchbase\Cluster('localhost');
80$db = $cluster->openBucket('default');
81$db->upsert('testdoc', array('name'=>'Frank'));
82$res = $db->get('testdoc');
83var_dump($res->value);
84// array(1) {
85//   ["name"]=>
86//   string(5) "Frank"
87// }
88```
89
90## Documentation
91
92An extensive documentation is available on the Couchbase website.  Visit our
93[PHP Community](https://forums.couchbase.com/c/php-sdk) on
94the [Couchbase](http://developer.couchbase.com/documentation/server/current/sdk/php/start-using-sdk.html) website for the documentation as well as
95numerous examples and samples.
96
97To build PHP API reference, phpDocumentor have to be installed
98
99    pear channel-discover pear.phpdoc.org
100    pear install phpdoc/phpDocumentor
101
102That will bring phpdoc command into PATH. The following steps assume that current directory is the root of this repository:
103
104    ver=$(git describe | sed 's/^v//')
105    rm -rf couchbase-php-client-$ver
106    phpdoc --target couchbase-php-client-$ver --directory api
107
108After that all reference documentation will be stored in couchbase-php-client-2.3.0, if current tag is 2.3.0.
109
110## Source Control
111
112The source code is available at
113[https://github.com/couchbase/php-couchbase](https://github.com/couchbase/php-couchbase).
114
115To execute our test suite, simply install and execute phpunit against your
116checked out source code. Tests assume that you have Couchbase Server with
117default bucket running on localhost (otherwise use environment variable
118`CB_DSN`, `CB_ADMIN_USER`, `CB_ADMIN_PASSWORD`, `CB_BUCKET`, `CB_USER`,
119`CB_PASSWORD`. E.g. `CB_DSN=couchbase://192.168.1.42/ CB_BUCKET=travel-sample`).
120
121```bash
122curl -L https://phar.phpunit.de/phpunit.phar > ~/bin/phpunit
123chmod a+x ~/bin/phpunit
124# or just 'dnf install php-phpunit-PHPUnit' on Fedora 24+
125
126phpunit tests/
127```
128
129Integration tests require some prerequisites, so once they met, you can run integration
130tests with:
131
132```bash
133phpunit integration/
134```
135
136It is also possible to run tests using [CouchbaseMock](https://github.com/couchbase/CouchbaseMock):
137
138```bash
139CB_MOCK=1 phpunit tests/
140```
141
142Server version guard might be specified by `CB_VERSION` (default is `4.6`). The tests which depend on functionality,
143which is not supported by `CB_VERSION`, will be skipped automatically.
144
145## License
146Copyright 2016-2017 Couchbase Inc.
147
148Licensed under the Apache License, Version 2.0.
149
150See
151[LICENSE](https://github.com/couchbaselabs/php-couchbase/blob/master/LICENSE)
152for further details.
153