| // Licensed to the Apache Software Foundation (ASF) under one or more |
| // contributor license agreements. See the NOTICE file distributed with |
| // this work for additional information regarding copyright ownership. |
| // The ASF licenses this file to You under the Apache License, Version 2.0 |
| // (the "License"); you may not use this file except in compliance with |
| // the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| = PHP Thin Client |
| |
| == Prerequisites |
| * link:http://php.net/manual/en/install.php[PHP version 7.2 or higher,window=_blank] and link:https://getcomposer.org/download[Composer Dependency Manager,window=_blank] |
| * php-xml module |
| * link:http://php.net/manual/en/mbstring.installation.php[PHP Multibyte String extension]. |
| Depending on your PHP configuration, you may need to additionally install/configure it. |
| |
| == Installation |
| |
| The thin client can be installed from the zip archive: |
| |
| * Download the link:https://ignite.apache.org/download.cgi#binaries[Apache Ignite binary package,window=_blank]. |
| * Unpack the archive and navigate to the `{IGNITE_HOME}/platforms/php` folder. |
| * Use the command below to install the package. |
| |
| [source,shell] |
| ---- |
| composer install --no-dev |
| ---- |
| |
| To use the client in your application, include the `vendor/autoload.php` file, generated by Composer, to your source code. |
| |
| [source,php] |
| ---- |
| 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. |
| |
| [source, php] |
| ---- |
| 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. |
| |
| [source, php] |
| ---- |
| include::code-snippets/php/ConnectingToCluster.php[tag=connecting,indent=0] |
| ---- |
| |
| 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 link:thin-clients/getting-started-with-thin-clients#client-connection-failover[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: |
| |
| [source, php] |
| ---- |
| include::code-snippets/php/UsingKeyValueApi.php[tag=createCache,indent=0] |
| ---- |
| |
| === Basic Key-Value Operations |
| |
| The following code snippet illustrates how to perform basic key-value operations with a cache instance: |
| |
| [source, php] |
| ---- |
| include::code-snippets/php/UsingKeyValueApi.php[tag=basicOperations,indent=0] |
| ---- |
| |
| //// |
| TODO |
| === 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. |
| |
| //// |
| *TODO: illustrate how to use the iterator in the example* |
| //// |
| |
| [source, php] |
| ---- |
| include::code-snippets/php/UsingKeyValueApi.php[tag=scanQry,indent=0] |
| ---- |
| |
| == Executing SQL Statements |
| The PHP thin client supports all link:sql-reference[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. |
| |
| [source, php] |
| ---- |
| include::code-snippets/php/UsingKeyValueApi.php[tag=executingSql,indent=0] |
| ---- |
| |
| == 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 link:thin-clients/getting-started-with-thin-clients#enabling-ssltls-for-thin-clients[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: |
| [source, php] |
| ---- |
| include::code-snippets/php/Security.php[tag=tls,indent=0] |
| ---- |
| |
| === Authentication |
| Configure link:security/authentication[authentication on the cluster side] and provide a valid user name and password in the client configuration. |
| |
| [source, php] |
| ---- |
| include::code-snippets/php/Security.php[tag=authentication,indent=0] |
| ---- |
| |
| |
| |