Edit

PHP Thin Client

Prerequisites

PHP version 7.2 or higher and Composer Dependency Manager
php-xml module
PHP Multibyte String extension. Depending on your PHP configuration, you may need to additionally install/configure it.

Installation

The PHP thin client is shipped as a Composer package and a zip archive. Use any of the methods to install the client in your environment.

Using Composer

composer require apache/apache-ignite-client

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

require_once __DIR__ . '/vendor/autoload.php';

Using ZIP Archive

The thin client can be installed from the zip archive available for download from the Apache Ignite website:

Download the Apache Ignite PHP Thin Client.
Unpack the archive and navigate to the root folder.
Use the command below to install the package.

composer install --no-dev

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

require_once "<php_client_root_dir>/vendor/autoload.php";

Creating a Client Instance

All operations 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 object 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 specified. 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 loses 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";

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 Ignite. 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 cursor 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.

Here 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('ignite');
$config->setPassword('ignite');
//$config->setTLSOptions($tlsOptions);

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

© 2024 The Apache Software Foundation.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.