PHP API overview

From Clusterpoint Wiki
Jump to: navigation, search

The CPS PHP API provides easier access to CPS from PHP. Some of the key concepts of using the API are outlined here.

Required includes

If You are going to be using the CPS_Simple API, You can simply include the cps_simple.php file, like this:


If You are going to be using the full CPS API, You have to include the cps_api.php file, like this:


If You don't know yet, which API you are going to use - read on, this document describes the difference between the two.


Before sending any requests, You have to create an instance of the CPS_Connection class. For its constructor You have to specify:

1) The connection string.
If you are connecting to a TCP socket, you should prefix the hostname with a tcp:// prefix. Also, You can specify a port number if it differs from the default one, e.g.:


On Clusterpoint DB versions 2.X you can connect locally to a UNIX socket, you should prefix its path with a unix:// prefix, e.g.:


If you are connecting over HTTP (lowest performance of the three options), you should specify the full URL to the HTTP gateway, including the http:// prefix, e.g.:


2) The storage name
3) Username for authentication
4) Password for authentication
5) (optional) Document root tag name. This is only required if your document root tag name is not "document"
6) (optional) Document ID Xpath. This is only required if your document ID xpath, as specified in the storage policy, is not "/document/id". you have to specify the full path from the root, including the root tag, separated by slashes, e.g.


An example connection:

$cpsConnection = new CPS_Connection("tcp://SERVER_IP:SERVER_PORT",


Two APIs are actually provided. If You are new to CPS, it's probably better to try the CPS_Simple API first, as it is much easier to use, and only to progress to the full CPS API when necessary.


The first one is the PHP CPS API that essentially provides the same amount of functionality as the XML API - You can send any command with any request options specified. In this API, for each request to the database You have to:
1) Create a request object - there are different types of request objects suited for different commands, e.g. CPS_SearchRequest class is for the 'search' command.
2) Set all the parameters for this request object with provided method (e.g. group parameters for search can be set with the CPS_SearchRequest::setGroup method, etc.)
3) Send the request using the CPS_Connection::sendRequest method. The method will return a response object, e.g. CPS_SearchResponse
4) Retrieve the required information from the response object using its methods, e.g. CPS_SearchResponse::getDocuments, CPS_SearchResponse::getFacets

$cpsConnection = new CPS_Connection("tcp://SERVER_IP:SERVER_PORT",
$searchRequest = new CPS_SearchRequest("test*",
$searchResponse = $cpsConnection->sendRequest($searchRequest);
$facets = $searchResponse->getFacets();

CPS_Simple API

This API option is suited for a majority of requests that don't require advanced parameters to be specified, and that only return a single type of data. This API is very simple to use, however there is a cost to that simplicity - through this API You don't have access to some advanced functionality of the CPS storage, such as facets, grouping and some other features that require explicitly specifying request parameters for the storage.
In order to use this API, You have to instantiate a CPS_Simple object with a CPS_Connection object as an argument, e.g.

$cps = new CPS_Simple($cpsConnection);

The CPS_Simple API now can simply be used by calling the methods of the CPS_Simple class, for example:

$documents = $cps->search('test*');



Error handling

All CPS objects will throw exceptions of type CPS_Exception upon receiving any error from the CPS storage, as well as upon receiving some invalid parameters (e.g. malformed documents). Multiple errors can be returned in one exception, if the storage has returned multiple errors. In order to prevent the exception from being shown to the user of Your application, it is advised to place all code dealing with CPS objects into a try-catch block, e.g.:

try {
  $cpsConnection = new CPS_Connection("tcp://SERVER_IP:SERVER_PORT",
  $cps = new CPS_Simple($cpsConnection);
  $documents = $cps->search('test*');
} catch (CPS_Exception $e) {
  foreach ($e->errors() as $error) {
    write_to_error_log($error['code'], $error['long_message']);

Note that multi-document modifying requests might return errors only for some of the document IDs, while the rest of the modifications will take place successfully. In order to detect these situations, You can check the document_id field inside the error array.

Request and response parameter formats

Most request and response parameters are simply strings and can be specified/retrieved as such. However, there is a number of parameters, that have to be specified in a specific format or with helper functions. For example, multiple formats are supported for specifying and retrieving document contents. These requirements are outlined here.

Search query

The search query is one of the fields that is specified as a raw XML string, so that complex querying is possible through the API. Due to this You have to either escape <, >, & characters in Your queries or compose the query using the helper functions CPS_QueryTerm and CPS_Term. The difference between these functions is that CPS_QueryTerm also escapes all search operators in a given term. This could be useful if You are passing the query directly from the user into the query string.

// $query = '{<xpath1>$term$</xpath1><xpath2>term2</xpath2}';
$query = '{' . CPS_Term('$term$', 'xpath1') . CPS_Term('term2', 'xpath2') . '}';
// $query = '{<xpath1><subxpath1>term1</subxpath1></xpath1><xpath2>term2</xpath2}'; 
$query = '{' . CPS_Term('term1', 'xpath1/subxpath1') . CPS_Term('term2', 'xpath2') . '}'; 
// $query = '{<xpath1>\$term\$</xpath1><xpath2>term2</xpath2}';
$query = '{' . CPS_QueryTerm('$term$', 'xpath1') . CPS_Term('term2', 'xpath2') . '}';
// $query = '<xpath1>&gt;5</xpath1>';
$query = CPS_Term('>5', 'xpath1');
$documents = $cps->search($query);

Search ordering parameters

Search ordering parameters could be specified as an XML string or an array of strings, but it is also possible to specify them completely using the helper functions CPS_RelevanceOrdering, CPS_NumericOrdering, CPS_LatLonDistanceOrdering and CPS_PlaneDistanceOrdering.
For example, the following request will return results ordered by the fields user_count in a descending order. If user_count is equal for several documents, they will be sorted by relevance among themselves:

$searchRequest = new CPS_SearchRequest('query');
$searchRequest->setOrdering(array(CPS_NumericOrdering('user_count', 'desc'), CPS_RelevanceOrdering()))
$searchResponse = $cpsConnection->sendRequest($searchRequest);

Document contents

Document contents can be specified and retrieved in 3 different formats. Where You place document contents in the request, the format of the document contents will be detected automatically (thus, You can even use a different format for each document for multi-document requests). When retrieving document contents from a request, relevant API calls have a $returnType parameter, which can specify the document content format that would be returned. The following formats are supported:
1) SimpleXMLElement nodes. This is the default. Fields can be easily retrieved and set, e.g. the following example retrieves documents from the storage and replaces a certain field:

// creating CPS_Simple object from an existing CPS_Connection object
$cpsSimple = new CPS_Simple($cpsConnection);
// specifying an array of document IDs to retrieve
$documentIds = array('id1', 'id2');
// initializing the array for the update request
$update_docs = array();
foreach ($cpsSimple->retrieveMultiple($documentIds) as $id => $document) {
  // for documents that don't have the <b> tags already
  if (substr($document->title, 0, 3) != '<b>') {
    // change $document->title
    $document->title = '<b>' . $document->title . '</b>';
    // insert into the array of documents to update
    $update_docs[$id] = $document;
// run the update command on these documents

2) StdClass objects. This format can be selected by setting the $returnType argument to DOC_TYPE_STDCLASS. Fields can be retrieved and set in essentially the same way as the SimpleXMLElement objects.
3) Associative arrays. This format can be selected by setting the $returnType argument to DOC_TYPE_ARRAY. While associative arrays maybe very intuitive to work with if You know exactly the document structure that You are going to get, they are somewhat difficult to navigate if the document structure is variable. Also, they are great for update/insert/partial-replace requests.

// creating CPS_Simple object from an existing CPS_Connection object
$cpsSimple = new CPS_Simple($cpsConnection);
// retrieving single document with id = id1
$document = $cpsSimple->retrieveSingle('id1', DOC_TYPE_ARRAY);
echo 'Retrieved document under the title ' . $document['title'] . '<br />';
// generating a value for the key field randomly
$document['body']['key'] = uniqid();
$cpsSimple->updateSingle('id1', $document);

List parameter

The list parameter specifies which fields are to be returned for list-last, list-first and search requests. It can be specified with an associative array with xpaths of the fields as keys and listing options as values. E.g.

// creating CPS_Simple object from an existing CPS_Connection object
$cpsSimple = new CPS_Simple($cpsConnection);
// lists the document tag and all tags under it, except for the text/full_text tag
$listParam = array('document' => 'yes', 'body/full_text' => 'no');
// listing last 10 documents
$documents = $cpsSimple->listLast($listParam, 0, 10);

Further reading

More information can be obtained by reading the PHP API Reference, as well as PHP API usage examples for each particular command in the Wiki manual