PHP Connector

php-tdengine 是由社区贡献的 PHP 连接器扩展,还特别支持了 Swoole 协程化。

PHP 连接器依赖 TDengine 客户端驱动。

项目地址:https://github.com/Yurunsoft/php-tdengine

TDengine 服务端或客户端安装后,taos.h 位于:

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

TDengine 客户端驱动的动态库位于:

  • Linux: /usr/local/taos/driver/libtaos.so
  • Windows: C:\TDengine\taos.dll

支持的平台

  • Windows、Linux、MacOS

  • PHP >= 7.4

  • TDengine >= 2.0

  • Swoole >= 4.8 (可选)

支持的版本

TDengine 客户端驱动的版本号与 TDengine 服务端的版本号是一一对应的强对应关系,建议使用与 TDengine 服务端完全相同的客户端驱动。虽然低版本的客户端驱动在前三段版本号一致(即仅第四段版本号不同)的情况下也能够与高版本的服务端相兼容,但这并非推荐用法。强烈不建议使用高版本的客户端驱动访问低版本的服务端。

安装步骤

安装 TDengine 客户端驱动

TDengine 客户端驱动的安装请参考 安装指南

编译安装 php-tdengine

下载代码并解压:

  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

版本 v1.0.2 可替换为任意更新的版本,可在 TDengine PHP Connector 发布历史

非 Swoole 环境:

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

手动指定 tdengine 目录:

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

--with-tdengine-dir= 后跟上 tdengine 目录。 适用于默认找不到的情况,或者 MacOS 系统用户。

Swoole 环境:

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

启用扩展:

方法一:在 php.ini 中加入 extension=tdengine

方法二:运行带参数 php -dextension=tdengine test.php

示例程序

本节展示了使用客户端驱动访问 TDengine 集群的常见访问方式的示例代码。

所有错误都会抛出异常: TDengine\Exception\TDengineException

建立连接

建立连接

  1. <?php
  2. use TDengine\Connection;
  3. use TDengine\Exception\TDengineException;
  4. try {
  5. // instantiate
  6. $host = 'localhost';
  7. $port = 6030;
  8. $username = 'root';
  9. $password = 'taosdata';
  10. $dbname = null;
  11. $connection = new Connection($host, $port, $username, $password, $dbname);
  12. // connect
  13. $connection->connect();
  14. } catch (TDengineException $e) {
  15. // throw exception
  16. throw $e;
  17. }

查看源码

插入数据

插入数据

  1. <?php
  2. use TDengine\Connection;
  3. use TDengine\Exception\TDengineException;
  4. try {
  5. // instantiate
  6. $host = 'localhost';
  7. $port = 6030;
  8. $username = 'root';
  9. $password = 'taosdata';
  10. $dbname = 'power';
  11. $connection = new Connection($host, $port, $username, $password, $dbname);
  12. // connect
  13. $connection->connect();
  14. // insert
  15. $connection->query('CREATE DATABASE if not exists power');
  16. $connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)');
  17. $resource = $connection->query(<<<'SQL'
  18. 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)
  19. power.d1002 USING power.meters TAGS(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
  20. 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)
  21. 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)
  22. SQL);
  23. // get affected rows
  24. var_dump($resource->affectedRows());
  25. } catch (TDengineException $e) {
  26. // throw exception
  27. throw $e;
  28. }

查看源码

同步查询

同步查询

  1. <?php
  2. use TDengine\Connection;
  3. use TDengine\Exception\TDengineException;
  4. try {
  5. // instantiate
  6. $host = 'localhost';
  7. $port = 6030;
  8. $username = 'root';
  9. $password = 'taosdata';
  10. $dbname = 'power';
  11. $connection = new Connection($host, $port, $username, $password, $dbname);
  12. // connect
  13. $connection->connect();
  14. $resource = $connection->query('SELECT ts, current FROM meters LIMIT 2');
  15. var_dump($resource->fetch());
  16. } catch (TDengineException $e) {
  17. // throw exception
  18. throw $e;
  19. }

查看源码

参数绑定

参数绑定

  1. <?php
  2. use TDengine\Connection;
  3. use TDengine\Exception\TDengineException;
  4. try {
  5. // instantiate
  6. $host = 'localhost';
  7. $port = 6030;
  8. $username = 'root';
  9. $password = 'taosdata';
  10. $dbname = 'power';
  11. $connection = new Connection($host, $port, $username, $password, $dbname);
  12. // connect
  13. $connection->connect();
  14. // insert
  15. $connection->query('CREATE DATABASE if not exists power');
  16. $connection->query('CREATE STABLE if not exists meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)');
  17. $stmt = $connection->prepare('INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)');
  18. // set table name and tags
  19. $stmt->setTableNameTags('d1001', [
  20. // same format as parameter binding
  21. [TDengine\TSDB_DATA_TYPE_BINARY, 'California.SanFrancisco'],
  22. [TDengine\TSDB_DATA_TYPE_INT, 2],
  23. ]);
  24. $stmt->bindParams([
  25. [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611249],
  26. [TDengine\TSDB_DATA_TYPE_FLOAT, 10.3],
  27. [TDengine\TSDB_DATA_TYPE_INT, 219],
  28. [TDengine\TSDB_DATA_TYPE_FLOAT, 0.31],
  29. ]);
  30. $stmt->bindParams([
  31. [TDengine\TSDB_DATA_TYPE_TIMESTAMP, 1648432611749],
  32. [TDengine\TSDB_DATA_TYPE_FLOAT, 12.6],
  33. [TDengine\TSDB_DATA_TYPE_INT, 218],
  34. [TDengine\TSDB_DATA_TYPE_FLOAT, 0.33],
  35. ]);
  36. $resource = $stmt->execute();
  37. // get affected rows
  38. var_dump($resource->affectedRows());
  39. } catch (TDengineException $e) {
  40. // throw exception
  41. throw $e;
  42. }

查看源码

常量

常量说明
TDengine\TSDB_DATA_TYPE_NULLnull
TDengine\TSDB_DATA_TYPE_BOOLbool
TDengine\TSDB_DATA_TYPE_TINYINTtinyint
TDengine\TSDB_DATA_TYPE_SMALLINTsmallint
TDengine\TSDB_DATA_TYPE_INTint
TDengine\TSDB_DATA_TYPE_BIGINTbigint
TDengine\TSDB_DATA_TYPE_FLOATfloat
TDengine\TSDB_DATA_TYPE_DOUBLEdouble
TDengine\TSDB_DATA_TYPE_BINARYbinary
TDengine\TSDB_DATA_TYPE_TIMESTAMPtimestamp
TDengine\TSDB_DATA_TYPE_NCHARnchar
TDengine\TSDB_DATA_TYPE_UTINYINTutinyint
TDengine\TSDB_DATA_TYPE_USMALLINTusmallint
TDengine\TSDB_DATA_TYPE_UINTuint
TDengine\TSDB_DATA_TYPE_UBIGINTubigint