PHP Connector

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

PHP Connector 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、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

Version number v1.0.2 is only for example, it can be replaced to any newer version, please find available versions in TDengine PHP Connector Releases.

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 connector to access TDengine cluster are demonstrated.

Any error would throw exception: TDengine\Exception\TDengineException

Establish Conection

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