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：

1. curl -L -o php-tdengine.tar.gz https://github.com/Yurunsoft/php-tdengine/archive/refs/tags/v1.0.2.tar.gz \
2. && mkdir php-tdengine \
3. && 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：

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

Specify TDengine location：

1. 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：

1. 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

1. <?php

3. use TDengine\Connection;
4. use TDengine\Exception\TDengineException;

6. try {
7. // instantiate
8. $host = 'localhost';
9. $port = 6030;
10. $username = 'root';
11. $password = 'taosdata';
12. $dbname = null;
13. $connection = new Connection($host, $port, $username, $password, $dbname);

15. // connect
16. $connection->connect();
17. } catch (TDengineException $e) {
18. // throw exception
19. throw $e;
20. }

view source code

Insert Data

Insert Data

1. <?php

3. use TDengine\Connection;
4. use TDengine\Exception\TDengineException;

6. try {
7. // instantiate
8. $host = 'localhost';
9. $port = 6030;
10. $username = 'root';
11. $password = 'taosdata';
12. $dbname = 'power';
13. $connection = new Connection($host, $port, $username, $password, $dbname);

15. // connect
16. $connection->connect();

18. // insert
19. $connection->query('CREATE DATABASE if not exists power');
20. $connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)');
21. $resource = $connection->query(<<<'SQL'
22. 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)
23. power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
24. 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)
25. 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)
26. SQL);

28. // get affected rows
29. var_dump($resource->affectedRows());
30. } catch (TDengineException $e) {
31. // throw exception
32. throw $e;
33. }

view source code

Synchronous Query

Synchronous Query

1. <?php

3. use TDengine\Connection;
4. use TDengine\Exception\TDengineException;

6. try {
7. // instantiate
8. $host = 'localhost';
9. $port = 6030;
10. $username = 'root';
11. $password = 'taosdata';
12. $dbname = 'power';
13. $connection = new Connection($host, $port, $username, $password, $dbname);

15. // connect
16. $connection->connect();

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

view source code

Parameter Binding

Parameter Binding

1. <?php

3. use TDengine\Connection;
4. use TDengine\Exception\TDengineException;

6. try {
7. // instantiate
8. $host = 'localhost';
9. $port = 6030;
10. $username = 'root';
11. $password = 'taosdata';
12. $dbname = 'power';
13. $connection = new Connection($host, $port, $username, $password, $dbname);

15. // connect
16. $connection->connect();

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

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

30. $stmt->bindParams([
31. [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611249],
32. [TDengine\TSDB_DATA_TYPE_FLOAT, 10.3],
33. [TDengine\TSDB_DATA_TYPE_INT, 219],
34. [TDengine\TSDB_DATA_TYPE_FLOAT, 0.31],
35. ]);
36. $stmt->bindParams([
37. [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611749],
38. [TDengine\TSDB_DATA_TYPE_FLOAT, 12.6],
39. [TDengine\TSDB_DATA_TYPE_INT, 218],
40. [TDengine\TSDB_DATA_TYPE_FLOAT, 0.33],
41. ]);
42. $resource = $stmt->execute();

44. // get affected rows
45. var_dump($resource->affectedRows());
46. } catch (TDengineException $e) {
47. // throw exception
48. throw $e;
49. }

view source code

Constants