Skip to main content

PHP Client Library

php-tdengine is the TDengine PHP client library provided by TDengine community. In particular, it supports Swoole coroutine.

PHP client library relies on TDengine client driver.

Project Repository: https://github.com/Yurunsoft/php-tdengine

After TDengine client or server is installed, taos.h is located at:

  • Linux: /usr/local/taos/include
  • Windows: C:\TDengine\include
  • macOS: /usr/local/include

TDengine client driver is located at:

  • Linux: /usr/local/taos/driver/libtaos.so
  • Windows: C:\TDengine\taos.dll
  • macOS: /usr/local/lib/libtaos.dylib

Supported Platforms

  • Windows, Linux, and macOS

  • PHP >= 7.4

  • TDengine >= 2.0

  • Swoole >= 4.8 (Optional)

Supported Versions

Because the version of TDengine client driver is tightly associated with that of TDengine server, it's strongly suggested to use the client driver of same version as TDengine server, even though the client driver can work with TDengine server if the first 3 sections of the versions are same.

Installation

Install TDengine Client Driver

Regarding how to install TDengine client driver please refer to Install Client Driver

Install php-tdengine

**Download Source Code Package and Unzip: **

curl -L -o php-tdengine.tar.gz https://github.com/Yurunsoft/php-tdengine/archive/refs/tags/v1.0.2.tar.gz \
&& mkdir php-tdengine \
&& tar -xzf php-tdengine.tar.gz -C php-tdengine --strip-components=1

**Non-Swoole Environment: **

phpize && ./configure && make -j && make install

**Specify TDengine location: **

phpize && ./configure --with-tdengine-dir=/usr/local/Cellar/tdengine/3.0.0.0 && make -j && make install

--with-tdengine-dir= is followed by TDengine location. It's useful in case TDengine installatio location can't be found automatically or MacOS.

**Swoole Environment: **

phpize && ./configure --enable-swoole && make -j && make install

Enable Extension:

Option One: Add extension=tdengine in php.ini.

Option Two: Use CLI php -dextension=tdengine test.php.

Sample Programs

In this section a few sample programs which use TDengine PHP client library to access TDengine cluster are demonstrated.

Any error would throw exception: TDengine\Exception\TDengineException

Establish Connection

Establish Connection
<?php

use TDengine\Connection;
use TDengine\Exception\TDengineException;

try {
// instantiate
$host = 'localhost';
$port = 6030;
$username = 'root';
$password = 'taosdata';
$dbname = null;
$connection = new Connection($host, $port, $username, $password, $dbname);

// connect
$connection->connect();
} catch (TDengineException $e) {
// throw exception
throw $e;
}

view source code

Insert Data

Insert Data
<?php

use TDengine\Connection;
use TDengine\Exception\TDengineException;

try {
// instantiate
$host = 'localhost';
$port = 6030;
$username = 'root';
$password = 'taosdata';
$dbname = 'power';
$connection = new Connection($host, $port, $username, $password, $dbname);

// connect
$connection->connect();

// insert
$connection->query('CREATE DATABASE if not exists power');
$connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)');
$resource = $connection->query(<<<'SQL'
INSERT INTO power.d1001 USING power.meters TAGS(California.SanFrancisco, 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) ('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)
power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
power.d1003 USING power.meters TAGS(California.LosAngeles, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)
power.d1004 USING power.meters TAGS(California.LosAngeles, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)
SQL);

// get affected rows
var_dump($resource->affectedRows());
} catch (TDengineException $e) {
// throw exception
throw $e;
}

view source code

Synchronous Query

Synchronous Query
<?php

use TDengine\Connection;
use TDengine\Exception\TDengineException;

try {
// instantiate
$host = 'localhost';
$port = 6030;
$username = 'root';
$password = 'taosdata';
$dbname = 'power';
$connection = new Connection($host, $port, $username, $password, $dbname);

// connect
$connection->connect();

$resource = $connection->query('SELECT ts, current FROM meters LIMIT 2');
var_dump($resource->fetch());
} catch (TDengineException $e) {
// throw exception
throw $e;
}

view source code

Parameter Binding

Parameter Binding
<?php

use TDengine\Connection;
use TDengine\Exception\TDengineException;

try {
// instantiate
$host = 'localhost';
$port = 6030;
$username = 'root';
$password = 'taosdata';
$dbname = 'power';
$connection = new Connection($host, $port, $username, $password, $dbname);

// connect
$connection->connect();

// insert
$connection->query('CREATE DATABASE if not exists power');
$connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)');
$stmt = $connection->prepare('INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)');

// set table name and tags
$stmt->setTableNameTags('d1001', [
// same format as parameter binding
[TDengine\TSDB_DATA_TYPE_BINARY, 'California.SanFrancisco'],
[TDengine\TSDB_DATA_TYPE_INT, 2],
]);

$stmt->bindParams([
[TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611249],
[TDengine\TSDB_DATA_TYPE_FLOAT, 10.3],
[TDengine\TSDB_DATA_TYPE_INT, 219],
[TDengine\TSDB_DATA_TYPE_FLOAT, 0.31],
]);
$stmt->bindParams([
[TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611749],
[TDengine\TSDB_DATA_TYPE_FLOAT, 12.6],
[TDengine\TSDB_DATA_TYPE_INT, 218],
[TDengine\TSDB_DATA_TYPE_FLOAT, 0.33],
]);
$resource = $stmt->execute();

// get affected rows
var_dump($resource->affectedRows());
} catch (TDengineException $e) {
// throw exception
throw $e;
}

view source code

Constants

ConstantDescription
TDengine\TSDB_DATA_TYPE_NULLnull
TDengine\TSDB_DATA_TYPE_BOOLbool
TDengine\TSDB_DATA_TYPE_TINYINTtinyint
TDengine\TSDB_DATA_TYPE_SMALLINTsmallint
TDengine\TSDB_DATA_TYPE_INTint
TDengine\TSDB_DATA_TYPE_BIGINTbigint
TDengine\TSDB_DATA_TYPE_FLOATfloat
TDengine\TSDB_DATA_TYPE_DOUBLEdouble
TDengine\TSDB_DATA_TYPE_BINARYbinary
TDengine\TSDB_DATA_TYPE_TIMESTAMPtimestamp
TDengine\TSDB_DATA_TYPE_NCHARnchar
TDengine\TSDB_DATA_TYPE_UTINYINTutinyint
TDengine\TSDB_DATA_TYPE_USMALLINTusmallint
TDengine\TSDB_DATA_TYPE_UINTuint
TDengine\TSDB_DATA_TYPE_UBIGINTubigint