PHP Client Library

php-tdengine is a PHP connector extension contributed by the community, which also specifically supports Swoole coroutine.

The PHP connector depends on the TDengine client driver.

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

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

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

The dynamic library of the 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, macOS
PHP >= 7.4
TDengine >= 2.0
Swoole >= 4.8 (optional)

Supported Versions

The version number of the TDengine client driver has a strong correspondence with the version number of the TDengine server. It is recommended to use a client driver that is exactly the same as the TDengine server. Although lower version client drivers can be compatible with higher version servers if the first three segments of the version number match (only the fourth segment differs), this is not recommended. It is strongly advised not to use a higher version client driver to access a lower version server.

Installation Steps

Install TDengine Client Driver

For installation of the TDengine client driver, please refer to the Installation Guide.

Compile and Install php-tdengine

Download the code and unzip it:

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

Version v1.0.2 can be replaced with any newer version, which can be found in the TDengine PHP Connector Release History.

Non-Swoole Environment:

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

Manually Specify the TDengine Directory:

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

Follow --with-tdengine-dir= with the TDengine directory. This is applicable for situations where the default cannot be found or for macOS users.

Swoole Environment:

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

Enable the Extension:

Method 1: Add extension=tdengine to php.ini

Method 2: Run with the parameter php -dextension=tdengine test.php

Example Programs

This section shows example code for common access methods to access the TDengine cluster using the client driver.

All errors will throw exceptions: 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_VARBINARY`	varbinary
`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 Steps​

Install TDengine Client Driver​

Compile and Install php-tdengine​

Example Programs​

Establish Connection​

Insert Data​

Synchronous Query​

Parameter Binding​

Constants​

Support and Feedback

Supported Platforms

Supported Versions

Installation Steps

Install TDengine Client Driver

Compile and Install php-tdengine

Example Programs

Establish Connection

Insert Data

Synchronous Query

Parameter Binding

Constants