当前位置：首页 > news >正文

TDengine 语言连接器（PHP）

news 来源：原创 2025/5/16 2:47:37

简介

PHP 语言广泛用于 Web 开发的开源脚本语言。它语法简单，容易学习，既支持面向过程，也支持面向对象编程。具有跨平台性，能与多种数据库交互，可与 HTML 等前端技术配合，动态生成网页内容。常用于开发各类网站、API 及编写命令行脚本，拥有大量开源项目和活跃社区，在 Web 开发领域始终占据重要地位。

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

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

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

TDengine 服务端或客户端安装后，taos.h 位于：

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

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

Linux：/usr/local/taos/driver/libtaos.so
Windows：C:\TDengine\taos.dll
macOS：/usr/local/lib/libtaos.dylib

支持的平台

Windows、Linux、MacOS
PHP >= 7.4
TDengine >= 2.0
Swoole >= 4.8 (可选)

支持的版本

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

安装步骤

安装 TDengine 客户端驱动

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

编译安装 php-tdengine

下载代码并解压：

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

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

非 Swoole 环境：

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

手动指定 tdengine 目录：

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

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

Swoole 环境：

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

启用扩展：

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

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

示例程序

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

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

建立连接

<?phpuse 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 exceptionthrow $e;
}

插入数据

<?phpuse 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 rowsvar_dump($resource->affectedRows());
} catch (TDengineException $e) {// throw exceptionthrow $e;
}

同步查询

<?phpuse 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 exceptionthrow $e;
}

参数绑定

<?phpuse 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 rowsvar_dump($resource->affectedRows());
} catch (TDengineException $e) {// throw exceptionthrow $e;
}

常量

常量	说明
`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