Download the PHP package triagens/arangodb without Composer
On this page you can find all versions of the php package triagens/arangodb. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download triagens/arangodb
More information about triagens/arangodb
Files in triagens/arangodb
Package arangodb
Short Description ArangoDB PHP client
License Apache-2.0
Homepage https://github.com/arangodb/arangodb-php
Informations about the package arangodb
ArangoDB-PHP - A PHP client for ArangoDB
This driver for ArangoDB, called the ArangoDB-PHP client,
allows REST-based access to documents on the server. The DocumentHandler class
should be used for these purposes. There is an example for REST-based documents
access in the examples/document.php
file.
Furthermore, the PHP client also allows to issue more AQL complex queries using
the Statement class. There is an example for this kind of statements in the
examples/aql-query.php
file.
To use the PHP client, you must include the file autoloader.php
from the main
directory. The autoloader cares about loading additionally required classes on
the fly. The autoloader can be nested with other autoloaders.
The ArangoDB PHP client is an API that allows you to send and retrieve documents from ArangoDB from out of your PHP application. The client library itself is written in PHP and has no further dependencies but just plain PHP 5.6 (or higher).
The client library provides document and collection classes you can use to work with documents and collections in an object-oriented fashion. When exchanging document data with the server, the library internally uses the HTTP REST interface of ArangoDB. The library user does not have to care about this fact as all the details of the REST interface are abstracted by the client library.
Requirements
- PHP version 5.6 or higher
Note on PHP version support:
This driver ceases to support old PHP versions as soon as they have reached end-of-life status. Support is removed with the next minor or patch version of the driver to be released.
In general, it is recommended to always use the latest PHP versions in order to take advantage of all the improvements (especially in performance).
Important version information on ArangoDB-PHP
The ArangoDB-PHP driver version has to match with the ArangoDB version:
- ArangoDB-PHP v3.8.x is on par with the functionality of ArangoDB v3.8.x
- ArangoDB-PHP v3.9.x is on par with the functionality of ArangoDB v3.9.x
etc.
Installation using Composer or Git
To get started, you need PHP 5.6 or higher plus an ArangoDB server running on any host that you can access.
There are two alternative ways to get the ArangoDB PHP client:
- Using Composer
- Cloning the git repository
Alternative 1: Using Composer
If you use Composer, you can run the following command in a command-line to install the PHP client:
Alternative 2: Cloning the Git repository
When preferring this alternative, you need to have a Git client installed. To clone the ArangoDB-PHP client repository from GitHub, execute the following command in your project directory:
This creates an arangodb-php
subdirectory in your current directory. It
contains all the files of the client library. It also includes a dedicated
autoloader that you can use for autoloading the client libraries class files.
To invoke this autoloader, add the following line to your PHP files that need
the library:
The ArangoDB-PHP client's autoloader only cares about its own class files and does not handle any other files. That means it is fully nestable with other autoloaders.
If you do not wish to include autoload.php to load and setup the autoloader, you can invoke the autoloader directly:
Set up the connection
In order to use ArangoDB, you need to specify the connection options. You can do
so by creating a PHP array $connectionOptions
. Put this code into a file named
test.php
in your current directory:
This makes the client connect to ArangoDB
- running on localhost (
OPTION_HOST
) - on the default port 8529 (
OPTION_PORT
) - with a connection timeout of 3 seconds (
OPTION_TIMEOUT
)
When creating new documents in a collection that does not yet exist, you have the following choices:
-
auto-generate a new collection: if you prefer that, set
OPTION_CREATE
totrue
- fail with an error:
if you prefer this behavior, set
OPTION_CREATE
tofalse
When updating a document that was previously/concurrently updated by another user, you can select between the following behaviors:
-
last update wins: if you prefer this, set
OPTION_UPDATE_POLICY
to last - fail with a conflict error:
if you prefer that, set
OPTION_UPDATE_POLICY
to conflict
Setting up Active Failover
By default, the PHP client connects to a single endpoint only, by specifying a string value for the endpoint in the connection options, e.g.
To set up multiple servers to connect to, it is also possible to specify an array of servers instead:
Using this option requires ArangoDB 3.3 or higher and the database running in Active Failover mode.
The driver tries to connect to the first server endpoint in the endpoints array by default, and only try the following servers if no connection can be established. If no connection can be made to any server, the driver throws an exception.
As it is unknown to the driver which server from the array is the current leader, the driver connects to the specified servers in array order by default. However, to spare a few unnecessary connection attempts to failed servers, it is possible to set up caching (using Memcached) for the server list. The cached value contains the last working server first, so that as few connection attempts as possible need to be made.
In order to use this caching, it is required to install the Memcached module for PHP, and to set up the following relevant options in the connection options:
Create collections
This is just to show how a collection is created. For these examples it is not needed to create a collection prior to inserting a document, as we set
ArangoConnectionOptions::OPTION_CREATE
totrue
.
So, after we get the settings, we can start with creating a collection. We create a collection named users.
The below code first sets up the collection locally in a variable name $user
,
and then pushes it to the server and returns the collection ID created by the
server:
Create documents
After we created the collection, we can start with creating an initial document.
We create a user document in a collection named users. This collection does
not need to exist yet. The first document we insert in this collection creates
the collection on the fly. This is because we have set OPTION_CREATE
to true
in $connectionOptions
.
The below code first sets up the document locally in a variable name $user
,
and then pushes it to the server and returns the document ID created by the
server:
Document properties can be set by using the set()
method, or by directly
manipulating the document properties.
As you can see, sending a document to the server is achieved by calling the
save()
method on the client library's DocumentHandler class. It needs the
collection name (users in this case) plus the document object to be saved.
save()
returns the document ID as created by the server. The ID is a numeric
value that might or might not fit in a PHP integer.
Add exception handling
The above code works but it does not check for any errors. To make it work in the face of errors, we wrap it into some basic exception handlers:
Retrieve documents
To retrieve a document from the server, the get()
method of the
DocumentHandler class can be used. It needs the collection name plus a
document ID. There is also the getById()
method which is an alias for get()
.
Whenever the document ID is yet unknown, but you want to fetch a document from
the server by any of its other properties, you can use the
CollectionHandler->byExample()
method. It allows you to provide an example of
the document that you are looking for. The example should either be a Document
object with the relevant properties set, or, a PHP array with the properties
that you are looking for:
This returns all documents from the specified collection (here: users) with
the properties provided in the example (here: that have an attribute name
with
a value of "John"
). The result is a cursor which can be iterated sequentially
or completely. We have chosen to get the complete result set above by calling
the cursor's getAll()
method.
CollectionHandler->byExample()
returns multiple documents if the example is
ambiguous.
Update documents
To update an existing document, the update()
method of the DocumentHandler
class can be used. In this example we want to:
- set state to
'CA'
- change the
likes
array
To remove an attribute using the update()
method, an option has to be passed
telling it to not keep attributes with null values. In this example we want to
remove the age
:
The document that is updated using the previous example must have been fetched
from the server before. If you want to update a document without having fetched
it from the server before, use updateById()
:
Replace documents
To completely replace an existing document, the replace()
method of the
DocumentHandler class can be used. In this example we want to remove the
state
attribute:
The document that is replaced using the previous example must have been fetched
from the server before. If you want to replace a document without having fetched
it from the server before, use replaceById()
:
Delete documents
To remove an existing document on the server, the remove()
method of the
DocumentHandler class can be used. remove()
just needs the document to be
removed as a parameter:
Note that the document must have been fetched from the server before. If you
haven't fetched the document from the server before, use the removeById()
method. This requires just the collection name (here: users) and the
document ID.
Drop collections
To drop an existing collection on the server, use the drop()
method of the
CollectionHandler class. drop()
just needs the name of the collection name
to be dropped:
Run AQL queries
To run an AQL query, use the Statement class.
The method Statement::execute
creates a Cursor object which can be used to
iterate over the query's result set.
Note: by default the Statement object will create a Cursor that converts each value into a Document object. This is normally the intended behavior for AQL queries that return entire documents. However, an AQL query can also return projections or any other data that cannot be converted into Document objects.
In order to suppress the conversion into Document objects, the Statement must be
given the _flat
attribute. This allows processing the results of arbitrary AQL
queries:
Bulk document handling
The ArangoDB-PHP driver provides a mechanism to easily fetch multiple documents from the same collection with a single request. All that needs to be provided is an array of document keys:
Custom Document class
If you want to use custom document class you can pass its name to
DocumentHandler or CollectionHandler using method setDocumentClass
.
Remember that Your class must extend \ArangoDBClient\Document
.
See the examples/customDocumentClass.php
file for more details.
Log exceptions
The driver provides a simple logging mechanism that is turned off by default.
If it is turned on, the driver logs all its exceptions using PHP's standard
error_log
mechanism. It calls PHP's error_log()
function for this. It
depends on the PHP configuration if and where exceptions are logged. Please
consult your php.ini
settings for further details.
To turn on exception logging in the driver, set a flag on the driver's Exception base class, from which all driver exceptions are subclassed:
To turn logging off, call its disableLogging
method:
Put it all together
Here is the full code that combines all the pieces outlined above:
More information
-
More example code, containing some code to create, delete and rename collections, is provided in the
examples
subdirectory that is provided with the library. - PHPDoc documentation for the complete library