Initialization and Configuration

❗️

This is a legacy Apache Ignite documentation

The new documentation is hosted here: https://ignite.apache.org/docs/latest/

The below sections explain the basic steps to work with Apache Ignite using PHP client.

Before connecting to Ignite from PHP thin client, you must start at least one Ignite cluster node. For instance, you can use the ignite.sh script from ignite-version/bin folder as follows:

$ ./ignite.sh

$ ignite.bat

Instantiating Ignite Client

A usage of the client starts with the creation of a Client object that connects a PHP application to the cluster.

It is possible to create as many Client objects as needed. All of them will work independently.

use Apache\Ignite\Client;

$client = new Client();

Configuring Ignite Client

The next step is to define a configuration for the client's connection by populating ClientConfiguration object.

A mandatory part of the configuration, which is specified in the constructor, is a list of endpoints of the Ignite nodes. At least one endpoint must be specified. A client connects to one node only - a random endpoint from the provided list. Other nodes, if provided, are used by the client for the "failover re-connection algorithm": the client tries to re-connect to the next random endpoint from the list if the current connection is lost.

Optional parts of the configuration can be specified using additional methods which include:

• Authentication using username/password
• SSL/TLS connection
• PHP connection options
  By default, the client establishes a non-secure connection with default connection options and does not use authentication.

The example below shows how to configure the client:

use Apache\Ignite\ClientConfiguration;

$clientConfiguration = new ClientConfiguration('127.0.0.1:10800');

The next example shows how to prepare Ignite Client Configuration with username/password authentication and additional connection options:

use Apache\Ignite\ClientConfiguration;

$clientConfiguration = (new ClientConfiguration('127.0.0.1:10800'))->
    setUserName('ignite')->
    setPassword('ignite')->
    setTimeout(5000);

Connecting to the Cluster

The next step is to connect the client to an Ignite cluster. The configuration for the client's connection, which includes endpoint(s) to connect to, is specified in the connect method.

If the client is not connected (including the case it can not successfully reconnect using the "failover re-connection algorithm"), the NoConnectionException is thrown for any operation with the Ignite cluster.

If the client unexpectedly losts the connection before or during an operation, the OperationStatusUnknownException is thrown. In this case, it is not known if the operation has been actually executed in the cluster or not. Note, the "failover re-connection algorithm" will be executed when the next operation is called by the application.

At any moment, an application can forcibly disconnect the client by calling the disconnect method.

When the client becomes disconnected, an application can call the connect method again - with the same or different configuration (eg. with a different list of endpoints).

use Apache\Ignite\Client;
use Apache\Ignite\ClientConfiguration;
use Apache\Ignite\Exception\ClientException;

function connectClient(): void
{
    $client = new Client();
    try {
        $clientConfiguration = new ClientConfiguration(
            '127.0.0.1:10800', '127.0.0.1:10801', '127.0.0.1:10802');
        // connect to Ignite node
        $client->connect($clientConfiguration);
    } catch (ClientException $e) {
        echo($e->getMessage());
    }
}

connectClient();

📘

PHP example files

PHP thin client contains fully workable examples to demonstrate the behavior of the client.

Cache Usage and Configuration

The next step is to obtain an object representing an Ignite cache. It's an instance of a PHP class with the CacheInterface.

The thin client provides several methods to work with Ignite caches and to obtain objects with the CacheInterface - get a cache by its name, create a cache with a specified name and optional cache configuration, get or create a cache, destroy a cache, etc.

It is possible to obtain as many objects with the CacheInterface as needed - for the same or different Ignite caches - and work with all of them in parallel.

The following example shows how to get access to a cache by name and destroy it later:

use Apache\Ignite\Client;
use Apache\Ignite\ClientConfiguration;
use Apache\Ignite\Exception\ClientException;

function getOrCreateCacheByName(): void
{
    $client = new Client();
    try {
        $client->connect(new ClientConfiguration('127.0.0.1:10800'));
        // get or create cache by name
        $cache = $client->getOrCreateCache('myCache');

        // perform cache key-value operations
        // ...

        // destroy cache
        $client->destroyCache('myCache');
    } catch (ClientException $e) {
        echo($e->getMessage());
    } finally {
        $client->disconnect();
    }
}

getOrCreateCacheByName();

The next example shows how to get access to a cache by name and with a configuration:

use Apache\Ignite\Client;
use Apache\Ignite\ClientConfiguration;
use Apache\Ignite\Cache\CacheConfiguration;
use Apache\Ignite\Exception\ClientException;

function createCacheByConfiguration(): void
{
    $client = new Client();
    try {
        $client->connect(new ClientConfiguration('127.0.0.1:10800'));
        // create cache by name and configuration
        $cache = $client->createCache(
            'myCache',
            (new CacheConfiguration())->setSqlSchema('PUBLIC'));
    } catch (ClientException $e) {
        echo($e->getMessage());
    } finally {
        $client->disconnect();
    }
}

createCacheByConfiguration();

This example shows how to get an existing cache by name:

use Apache\Ignite\Client;
use Apache\Ignite\ClientConfiguration;
use Apache\Ignite\Cache\CacheConfiguration;
use Apache\Ignite\Exception\ClientException;

function getExistingCache(): void
{
    $client = new Client();
    try {
        $client->connect(new ClientConfiguration('127.0.0.1:10800'));
        // create cache by name and configuration
        $cache = $client->getCache('myCache');
    } catch (ClientException $e) {
        echo($e->getMessage());
    } finally {
        $client->disconnect();
    }
}

getExistingCache();

Types Mapping Configuration

It is possible to specify concrete Ignite types for the key and/or the value of the cache. If the key and/or value is a non-primitive type (eg. a map, a collection, a complex object, etc.), it is possible to specify concrete Ignite types for fields of that objects as well.

If Ignite type is not explicitly specified for some field, the client tries to make automatic default mapping between PHP types and Ignite object types.

More details about types and mappings are clarified in the Data Types Mapping section.

use Apache\Ignite\Client;
use Apache\Ignite\ClientConfiguration;
use Apache\Ignite\Type\ObjectType;
use Apache\Ignite\Type\MapObjectType;
use Apache\Ignite\Exception\ClientException;

function setCacheKeyValueTypes(): void
{
    $client = new Client();
    try {
        $client->connect(new ClientConfiguration('127.0.0.1:10800'));
        $cache = $client->getOrCreateCache('myCache');
        $cache->setKeyType(ObjectType::INTEGER)->
            setValueType(new MapObjectType(
                MapObjectType::LINKED_HASH_MAP,
                ObjectType::SHORT,
                ObjectType::BYTE_ARRAY));
    } catch (ClientException $e) {
        echo($e->getMessage());
    } finally {
        $client->disconnect();
    }
}

setCacheKeyValueTypes();

Data Types

A mapping between Ignite types defined by the Binary Client Protocol and PHP types occurs every time an application writes or reads a field to/from an Ignite via the client's API. The field here is any data stored in Ignite - the whole key or value of an Ignite entry, an element of an array or set, a field of a complex object, etc.

The client supports two cases of mapping:

• Explicit mapping - Using the client's API methods, an application can explicitly specify an Ignite type for a particular field. The client uses this information to transform the field from PHP type to Ignite type and vice versa during the read/write operations.
• Default mapping - It defines what happens if an application does not use the explicit type mapping for a field.

Mappings between Ignite and PHP types during the read/write operations are described here

Complex Object Type Support

The client provides two ways to operate with Ignite Complex Object type - in the deserialized form and the binary form.

An application can specify an Ignite type of a field by an instance of the ComplexObjectType class which references a PHP class. In this case, when the application reads a value of the field, the client deserializes the received Ignite Complex Object and returns it to the client as an instance of the referenced PHP class. When the application writes a value of the field, the client expects an instance of the referenced PHP class and serializes it to the Ignite Complex Object.

If an application does not specify an Ignite type of a field and reads a value of the field, the client returns the received Ignite Complex Object as an instance of the BinaryObject class - a binary form of the Ignite Complex Object. The BinaryObject allows working with its content (read and write values of the object's fields, add and remove the fields, etc.) avoiding deserialization. Also, the application can create an instance of the BinaryObject class from a PHP object. An application can write the BinaryObject as a value of a field into Ignite, if that field has no explicitly specified Ignite type.

The client takes care of obtaining or registering information about Ignite Complex Object type, including schema, from/at Ignite cluster. It is done automatically by the client, when required for reading or writing of the Ignite Complex Object from/to Ignite.

Supported APIs

The client API specification can be found here.

The client supports all operations and types from the Binary Client Protocol except the following not-applicable features:

• OP_REGISTER_BINARY_TYPE_NAME and OP_GET_BINARY_TYPE_NAME operations are not supported.
• Filter object for OP_QUERY_SCAN operation is not supported. OP_QUERY_SCAN operation itself is supported.
• It is not possible to register a new Ignite Enum type. Reading and writing items of the existing Ignite Enum types are supported.
• Raw data is not supported in the complex objects.

The following additional features are supported:

• SSL/TLS connection
• Failover re-connection algorithm

All API method calls are synchronous.

Enabling Debug

To switch on/off the client's debug output (including errors logging), call setDebug() method of the Ignite Client object. Debug output is disabled by default.

use Apache\Ignite\Client;

$client = new Client();
$client->setDebug(true);