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 is strongly correlated with the version number of the TDengine server. It is recommended to use the client driver that is exactly the same as the TDengine server. Although a lower version of the client driver can be compatible with a higher version of the server if the first three segments of the version number match (only the fourth segment is different), this is not recommended. It is strongly discouraged to use a higher version of the client driver to access a lower version of the server.

Installation Steps

Install TDengine Client Driver

Please refer to the Installation Guide for the installation of the TDengine client driver.

Compile and install php-tdengine

Download and unzip the code:

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, available at 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. Suitable for cases where it cannot be found by default, or for MacOS users.

Swoole environment:

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

Enable the extension:

Method one: Add extension=tdengine in php.ini

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

Example Program

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

All errors will throw an 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_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 Program​

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 Program

Establish Connection

Insert Data

Synchronous Query

Parameter Binding

Constants