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

<?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

<?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

<?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

<?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

Constant	Description
`TDengine\TSDB_DATA_TYPE_NULL`	null
`TDengine\TSDB_DATA_TYPE_BOOL`	bool
`TDengine\TSDB_DATA_TYPE_TINYINT`	tinyint
`TDengine\TSDB_DATA_TYPE_SMALLINT`	smallint
`TDengine\TSDB_DATA_TYPE_INT`	int
`TDengine\TSDB_DATA_TYPE_BIGINT`	bigint
`TDengine\TSDB_DATA_TYPE_FLOAT`	float
`TDengine\TSDB_DATA_TYPE_DOUBLE`	double
`TDengine\TSDB_DATA_TYPE_BINARY`	binary
`TDengine\TSDB_DATA_TYPE_TIMESTAMP`	timestamp
`TDengine\TSDB_DATA_TYPE_NCHAR`	nchar
`TDengine\TSDB_DATA_TYPE_UTINYINT`	utinyint
`TDengine\TSDB_DATA_TYPE_USMALLINT`	usmallint
`TDengine\TSDB_DATA_TYPE_UINT`	uint
`TDengine\TSDB_DATA_TYPE_UBIGINT`	ubigint

Supported Platforms​

Supported Versions​

Installation​

Install TDengine Client Driver​

Install php-tdengine​

Sample Programs​

Establish Connection​

Insert Data​

Synchronous Query​

Parameter Binding​

Constants​

Support and Feedback

Supported Platforms

Supported Versions

Installation

Install TDengine Client Driver

Install php-tdengine

Sample Programs

Establish Connection

Insert Data

Synchronous Query

Parameter Binding

Constants