GridGain Developers Hub
GitHub logo GridGain iso GridGain.com
GridGain Software Documentation

PHP Thin Client

Prerequisites

Installation

The php thin client source code comes with the GridGain distribution package under the {GRIDGAIN_HOME}/platforms/php/ directory. You can install it to your system using Composer, as shown below:

cd {GRIDGAIN_HOME}/platforms/php
composer install --no-dev

To use the client in your application, include the vendor/autoload.php file, generated by Composer, to your source code. For example:

require_once "{GRIDGAIN_HOME}/platforms/php/vendor/autoload.php";

Creating a Client Instance

All operation of the php thin client are performed through a Client instance. You can create as many Client instances as needed. All of them will work independently.

use Apache\Ignite\Client;

$client = new Client();

Connecting to Cluster

To connect to a cluster, define a ClientConfiguration objects with the desired connection parameters and use the Client.connect(…​) method.

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();

The ClientConfiguration constructor accepts a list of node endpoints. At least one endpoint must be specify. If you specify more than one, the thin client will use them for failover purposes.

If the client cannot connect to the cluster, a NoConnectionException is thrown when attempting to perform any remote operation.

If the client unexpectedly losts the connection before or during an operation, an OperationStatusUnknownException is thrown. In this case, it is not known if the operation has been actually executed in the cluster or not. The client will try to reconnect to the next node specified in the configuration when the next operation is called by the application.

Call the disconnect() method to close the connection.

Using Key-Value API

Getting/Creating a Cache Instance

The client instance provides three methods for obtaining an instance of a cache:

  • getCache(name) — returns an existing cache by name. The method does not verify if the cache exists in the cluster; instead, you will get an exception when attempting to perform any operation with the cache.

  • getOrCreateCache(name, config) — returns an existing cache by name or creates a cache with the given configuration.

  • createCache(name, config) — creates a cache with the given name and parameters.

This is how you can create a cache:

$cacheCfg = new CacheConfiguration();
$cacheCfg->setCacheMode(CacheConfiguration::CACHE_MODE_REPLICATED);
$cacheCfg->setWriteSynchronizationMode(CacheConfiguration::WRITE_SYNC_MODE_FULL_SYNC);

$cache = $client->getOrCreateCache('References', $cacheCfg);

Basic Key-Value Operations

The following code snippet illustrates how to perform basic key-value operations with a cache instance:

$val = array();
$keys = range(1, 100);
foreach ($keys as $number) {
    $val[] = new CacheEntry($number, strval($number));
}
$cache->putAll($val);

$replace = $cache->replaceIfEquals(1, '2', '3');
echo $replace ? 'true' : 'false'; //false
echo "\r\n";

$value = $cache->get(1);
echo $value; //1
echo "\r\n";

$replace = $cache->replaceIfEquals(1, "1", 3);
echo $replace ? 'true' : 'false'; //true
echo "\r\n";

$value = $cache->get(1);
echo $value; //3
echo "\r\n";

$cache->put(101, '101');

$cache->removeKeys($keys);
$sizeIsOne = $cache->getSize() == 1;
echo $sizeIsOne ? 'true' : 'false'; //true
echo "\r\n";

$value = $cache->get(101);
echo $value; //101
echo "\r\n";

$cache->removeAll();
$sizeIsZero = $cache->getSize() == 0;
echo $sizeIsZero ? 'true' : 'false'; //true
echo "\r\n";

Asynchronous Execution

Scan Queries

The Cache.query(ScanQuery) method can be used to fetch all entries from the cache. It returns a cursor object with the standard PHP Iterator interface — use this cursor to iterate over the result set lazily, one by one. In addition, the cursor has methods to get all results at once.

$cache = $client->getOrCreateCache('personCache');

$cache->put(1, new Person(1, 'John Smith'));
$cache->put(1, new Person(1, 'John Johnson'));

$qry = new ScanQuery();
$cache->query(new ScanQuery());

Executing SQL Statements

The PHP thin client supports all SQL commands that are supported by GridGain. The commands are executed via the query(SqlFieldQuery) method of the cache object. The method accepts an instance of SqlFieldsQuery that represents a SQL statement. The query() method returns a cursor object with the standard PHP Iterator interface — use this cursor to iterate over the result set lazily, one by one. In addition, the cursos has methods to get all results at once.

$create_table = new SqlFieldsQuery(
    sprintf('CREATE TABLE IF NOT EXISTS Person (id INT PRIMARY KEY, name VARCHAR) WITH "VALUE_TYPE=%s"', Person::class)
);
$create_table->setSchema('PUBLIC');
$cache->query($create_table)->getAll();

$key = 1;
$val = new Person(1, 'Person 1');

$insert = new SqlFieldsQuery('INSERT INTO Person(id, name) VALUES(?, ?)');
$insert->setArgs($val->id, $val->name);
$insert->setSchema('PUBLIC');
$cache->query($insert)->getAll();

$select = new SqlFieldsQuery('SELECT name FROM Person WHERE id = ?');
$select->setArgs($key);
$select->setSchema('PUBLIC');
$cursor = $cache->query($select);
//get the results; the `getAll()` methods closes the cursor; you do not have to call cursor.close();
$results = $cursor->getAll();

if (sizeof($results) != 0) {
    echo 'name = ' . $results[0][0];
    echo "\r\n";
}

Security

SSL/TLS

To use encrypted communication between the thin client and the cluster, you have to enable it both in the cluster configuration and the client configuration. Refer to the Enabling SSL/TLS for Thin Clients section for the instruction on the cluster configuration.

Below is an example configuration for enabling SSL in the thin client:

$tlsOptions = [
    'local_cert' => '/path/to/client/cert',
    'cafile' => '/path/to/ca/file',
    'local_pk' => '/path/to/key/file'
];

$config = new ClientConfiguration('localhost:10800');
$config->setTLSOptions($tlsOptions);

$client = new Client();
$client->connect($config);

Authentication

Configure authentication on the cluster side and provide a valid user name and password in the client configuration.

$config = new ClientConfiguration('localhost:10800');
$config->setUserName('gridgain');
$config->setPassword('gridgain');
//$config->setTLSOptions($tlsOptions);

$client = new Client();
$client->connect($config);

Authorization

Thin client authorization can be configured in the cluster. Refer to the Authorization page for details.