From 46ffb6cf8bf82f0eafd27e0db009a48d3f335e5e Mon Sep 17 00:00:00 2001 From: Yurun Date: Sat, 14 May 2022 22:31:18 +0800 Subject: [PATCH] docs: update PHP doc (#12429) * Update php doc * Fix --- docs-cn/01-intro/01-intro.md | 2 +- .../04-develop/01-connect/_connect_php.mdx | 3 ++ docs-cn/04-develop/01-connect/index.md | 46 ++++++++++++++++- .../03-insert-data/01-sql-writing.mdx | 8 +++ .../04-develop/03-insert-data/_php_sql.mdx | 3 ++ .../04-develop/03-insert-data/_php_stmt.mdx | 3 ++ docs-cn/04-develop/04-query-data/_php.mdx | 3 ++ docs-cn/04-develop/04-query-data/index.mdx | 4 ++ docs-cn/25-application/03-immigrate.md | 2 +- docs-examples/php/connect.php | 20 ++++++++ docs-examples/php/insert.php | 33 +++++++++++++ docs-examples/php/insert_stmt.php | 49 +++++++++++++++++++ docs-examples/php/query.php | 23 +++++++++ .../cn/08.connector/03.php/docs.md | 9 +++- 14 files changed, 203 insertions(+), 5 deletions(-) create mode 100644 docs-cn/04-develop/01-connect/_connect_php.mdx create mode 100644 docs-cn/04-develop/03-insert-data/_php_sql.mdx create mode 100644 docs-cn/04-develop/03-insert-data/_php_stmt.mdx create mode 100644 docs-cn/04-develop/04-query-data/_php.mdx create mode 100644 docs-examples/php/connect.php create mode 100644 docs-examples/php/insert.php create mode 100644 docs-examples/php/insert_stmt.php create mode 100644 docs-examples/php/query.php diff --git a/docs-cn/01-intro/01-intro.md b/docs-cn/01-intro/01-intro.md index d9ea9e1658..263a1b3cbb 100644 --- a/docs-cn/01-intro/01-intro.md +++ b/docs-cn/01-intro/01-intro.md @@ -40,7 +40,7 @@ TDengine 是一款高性能、分布式、支持 SQL 的时序数据库，其核 - **零管理**：安装、集群几秒搞定，无任何依赖，不用分库分表，系统运行状态监测能与 Grafana 或其他运维工具无缝集成。 -- **零学习成本**：采用 SQL 查询语言，支持 Python, Java, C/C++, Go, Rust, Node.js 等多种编程语言,与 MySQL 相似，零学习成本。 +- **零学习成本**：采用 SQL 查询语言，支持 Python, Java, C/C++, Go, Rust, Node.js, PHP 等多种编程语言,与 MySQL 相似，零学习成本。 - **无缝集成**：不用一行代码，即可与 Telegraf, Grafana, EMQX, Prometheus, StatsD, collectd, Matlab, R 等第三方工具无缝集成。 diff --git a/docs-cn/04-develop/01-connect/_connect_php.mdx b/docs-cn/04-develop/01-connect/_connect_php.mdx new file mode 100644 index 0000000000..2431df2a72 --- /dev/null +++ b/docs-cn/04-develop/01-connect/_connect_php.mdx @@ -0,0 +1,3 @@ +```php title="原生连接" +{{#include docs-examples/php/connect.php}} +``` diff --git a/docs-cn/04-develop/01-connect/index.md b/docs-cn/04-develop/01-connect/index.md index 8109d3f0ea..5ef1fa9be3 100644 --- a/docs-cn/04-develop/01-connect/index.md +++ b/docs-cn/04-develop/01-connect/index.md @@ -13,12 +13,13 @@ import ConnPythonNative from "./_connect_python.mdx"; import ConnCSNative from "./_connect_cs.mdx"; import ConnC from "./_connect_c.mdx"; import ConnR from "./_connect_r.mdx"; +import ConnPHP from "./_connect_php.mdx"; import InstallOnWindows from "../../14-reference/03-connector/_linux_install.mdx"; import InstallOnLinux from "../../14-reference/03-connector/_windows_install.mdx"; import VerifyLinux from "../../14-reference/03-connector/_verify_linux.mdx"; import VerifyWindows from "../../14-reference/03-connector/_verify_windows.mdx"; -TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C# 和 Rust 的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。 +TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C#、Rust 和 PHP 的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。 ## 连接器建立连接的方式 @@ -200,6 +201,46 @@ install.packages("RJDBC") 如果已经安装了 TDengine 服务端软件或 TDengine 客户端驱动 taosc， 那么已经安装了 C 连接器，无需额外操作。
+ + + +**下载代码并解压：** + +```shell +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.0` 可替换为任意更新的版本，可在 Release 中查看最新版本。 + +**非 Swoole 环境：** + +```shell +phpize && ./configure && make -j && make install +``` + +**手动指定 tdengine 目录：** + +```shell +phpize && ./configure --with-tdengine-dir=/usr/local/Cellar/tdengine/2.4.0.0 && make -j && make install +``` + +> `--with-tdengine-dir=` 后跟上 tdengine 目录。 +> 适用于默认找不到的情况，或者 MacOS 系统用户。 + +**Swoole 环境：** + +```shell +phpize && ./configure --enable-swoole && make -j && make install +``` + +**启用扩展：** + +方法一：在 `php.ini` 中加入 `extension=tdengine` + +方法二：运行带参数 `php -dextension=tdengine test.php + @@ -232,6 +273,9 @@ install.packages("RJDBC") + + + :::tip diff --git a/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx b/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx index 7a4ab3eb72..e63ffce6dd 100644 --- a/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx +++ b/docs-cn/04-develop/03-insert-data/01-sql-writing.mdx @@ -18,6 +18,8 @@ import CsSQL from "./_cs_sql.mdx"; import CsStmt from "./_cs_stmt.mdx"; import CSQL from "./_c_sql.mdx"; import CStmt from "./_c_stmt.mdx"; +import PhpSQL from "./_php_sql.mdx"; +import PhpStmt from "./_php_stmt.mdx"; ## SQL 写入简介 @@ -88,6 +90,9 @@ INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31) (1538548695000, 12.6, + + + :::note @@ -125,5 +130,8 @@ TDengine 也提供了支持参数绑定的 Prepare API，与 MySQL 类似，这 + + + diff --git a/docs-cn/04-develop/03-insert-data/_php_sql.mdx b/docs-cn/04-develop/03-insert-data/_php_sql.mdx new file mode 100644 index 0000000000..42d6a54847 --- /dev/null +++ b/docs-cn/04-develop/03-insert-data/_php_sql.mdx @@ -0,0 +1,3 @@ +```php +{{#include docs-examples/php/insert.php}} +``` diff --git a/docs-cn/04-develop/03-insert-data/_php_stmt.mdx b/docs-cn/04-develop/03-insert-data/_php_stmt.mdx new file mode 100644 index 0000000000..c1ba4ed3b1 --- /dev/null +++ b/docs-cn/04-develop/03-insert-data/_php_stmt.mdx @@ -0,0 +1,3 @@ +```php +{{#include docs-examples/php/insert_stmt.php}} +``` diff --git a/docs-cn/04-develop/04-query-data/_php.mdx b/docs-cn/04-develop/04-query-data/_php.mdx new file mode 100644 index 0000000000..6264bd99f5 --- /dev/null +++ b/docs-cn/04-develop/04-query-data/_php.mdx @@ -0,0 +1,3 @@ +```go +{{#include docs-examples/php/query.php}} +``` diff --git a/docs-cn/04-develop/04-query-data/index.mdx b/docs-cn/04-develop/04-query-data/index.mdx index aabe848ff4..6b7edc1230 100644 --- a/docs-cn/04-develop/04-query-data/index.mdx +++ b/docs-cn/04-develop/04-query-data/index.mdx @@ -13,6 +13,7 @@ import RustQuery from "./_rust.mdx"; import NodeQuery from "./_js.mdx"; import CsQuery from "./_cs.mdx"; import CQuery from "./_c.mdx"; +import PhpQuery from "./_php.mdx"; import PyAsync from "./_py_async.mdx"; import NodeAsync from "./_js_async.mdx"; import CsAsync from "./_cs_async.mdx"; @@ -150,6 +151,9 @@ Query OK, 5 row(s) in set (0.001521s) + + + :::note diff --git a/docs-cn/25-application/03-immigrate.md b/docs-cn/25-application/03-immigrate.md index 4cc4c2ed9a..7574977e85 100644 --- a/docs-cn/25-application/03-immigrate.md +++ b/docs-cn/25-application/03-immigrate.md @@ -14,7 +14,7 @@ title: OpenTSDB 应用迁移到 TDengine 的最佳实践 - 安装部署非常简单，单一安装包完成安装部署，不依赖其他的第三方软件，整个安装部署过程秒级搞定; - 提供的内建函数覆盖 OpenTSDB 支持的全部查询函数，还支持更多的时序数据查询函数、标量函数及聚合函数，支持多种时间窗口聚合、连接查询、表达式运算、多种分组聚合、用户定义排序、以及用户定义函数等高级查询功能。采用类 SQL 的语法规则，更加简单易学，基本上没有学习成本。 - 支持多达 128 个标签，标签总长度可达到 16 KB； -- 除 REST 接口之外，还提供 Java、Python、C、Rust、Go 等多种语言的接口，支持 JDBC 等多种企业级标准连接器协议。 +- 除 REST 接口之外，还提供 Java、Python、C、Rust、Go、PHP 等多种语言的接口，支持 JDBC 等多种企业级标准连接器协议。 如果我们将原本运行在 OpenTSDB 上的应用迁移到 TDengine 上，不仅可以有效地降低计算和存储资源的占用、减少部署服务器的规模，还能够极大减少运行维护的成本的输出，让运维管理工作更简单、更轻松，大幅降低总拥有成本。与 OpenTSDB 一样，TDengine 也已经进行了开源，不同的是，除了单机版，后者还实现了集群版开源，被厂商绑定的顾虑一扫而空。 diff --git a/docs-examples/php/connect.php b/docs-examples/php/connect.php new file mode 100644 index 0000000000..5af77b9768 --- /dev/null +++ b/docs-examples/php/connect.php @@ -0,0 +1,20 @@ +connect(); +} catch (TDengineException $e) { + // 连接失败捕获异常 + throw $e; +} diff --git a/docs-examples/php/insert.php b/docs-examples/php/insert.php new file mode 100644 index 0000000000..0d9cfc4843 --- /dev/null +++ b/docs-examples/php/insert.php @@ -0,0 +1,33 @@ +connect(); + + // 插入 + $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(Beijing.Chaoyang, 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(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000) + power.d1003 USING power.meters TAGS(Beijing.Haidian, 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(Beijing.Haidian, 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); + + // 影响行数 + var_dump($resource->affectedRows()); +} catch (TDengineException $e) { + // 捕获异常 + throw $e; +} diff --git a/docs-examples/php/insert_stmt.php b/docs-examples/php/insert_stmt.php new file mode 100644 index 0000000000..5d4b4809d2 --- /dev/null +++ b/docs-examples/php/insert_stmt.php @@ -0,0 +1,49 @@ +connect(); + + // 插入 + $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(?, ?, ?, ?)'); + + // 设置表名和标签 + $stmt->setTableNameTags('d1001', [ + // 支持格式同参数绑定 + [TDengine\TSDB_DATA_TYPE_BINARY, 'Beijing.Chaoyang'], + [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(); + + // 影响行数 + var_dump($resource->affectedRows()); +} catch (TDengineException $e) { + // 捕获异常 + throw $e; +} diff --git a/docs-examples/php/query.php b/docs-examples/php/query.php new file mode 100644 index 0000000000..4e86a2cec7 --- /dev/null +++ b/docs-examples/php/query.php @@ -0,0 +1,23 @@ +connect(); + + $resource = $connection->query('SELECT ts, current FROM meters LIMIT 2'); + var_dump($resource->fetch()); +} catch (TDengineException $e) { + // 捕获异常 + throw $e; +} diff --git a/documentation20/cn/08.connector/03.php/docs.md b/documentation20/cn/08.connector/03.php/docs.md index eb772689e4..22e112f89e 100644 --- a/documentation20/cn/08.connector/03.php/docs.md +++ b/documentation20/cn/08.connector/03.php/docs.md @@ -26,7 +26,7 @@ **下载代码并解压：** ```shell -curl -L -o php-tdengine.tar.gz https://github.com/Yurunsoft/php-tdengine/archive/refs/tags/v1.0.0.tar.gz \ +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 ``` @@ -95,7 +95,7 @@ $db = null; // 实例化 $connection = new Connection($host, $port, $user, $pass, $db); // 连接 -$connection->connection(); +$connection->connect(); // 获取连接参数 $connection->getHost(); $connection->getPort(); @@ -140,6 +140,11 @@ $resource->close(); ```php // 查询 $stmt = $connection->prepare($sql); // 支持查询和插入，参数用?占位 +// 设置表名和标签 +$stmt->setTableNameTags('表名', [ + // 支持格式同参数绑定 + [TDengine\TSDB_DATA_TYPE_INT, 36], +]); // 绑定参数方法1 $stmt->bindParams( // [字段类型, 值] -- GitLab