PHP 連接器

php-tdengine

這是 Swoole 開發(fā)組成員，imi 框架作者宇潤開發(fā)的 php TDengine 客戶端擴(kuò)展，依賴 libtaos。

源代碼: https://github.com/Yurunsoft/php-tdengine

依賴

• PHP >= 7.4

• Swoole >= 4.8 （可選）

• TDengine客戶端 >= 2.0

特性列表

• 參數(shù)綁定
• 支持 Swoole 協(xié)程化
• 主流操作系統(tǒng)支持：Windows、Linux、MacOS
• 測試用例覆蓋

編譯安裝

下載代碼并解壓：

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 可替換為任意更新的版本，可在 Release 中查看最新版本。

非 Swoole 環(huán)境：

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

手動(dòng)指定 tdengine 目錄：

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

--with-tdengine-dir= 后跟上 tdengine 目錄。 適用于默認(rèn)找不到的情況，或者 MacOS 系統(tǒng)用戶。

Swoole 環(huán)境：

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

啟用擴(kuò)展：

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

方法二：運(yùn)行帶參數(shù) php -dextension=tdengine test.php

PHP 代碼編寫

所有錯(cuò)誤都會(huì)拋出異常: TDengine\Exception\TDengineException

基本：

use TDengine\Connection;

// 獲取擴(kuò)展版本號(hào)
var_dump(\TDengine\EXTENSION_VERSION);

// 設(shè)置客戶端選項(xiàng)
\TDengine\setOptions([
    \TDengine\TSDB_OPTION_LOCALE => 'en_US.UTF-8', // 區(qū)域
    \TDengine\TSDB_OPTION_CHARSET => 'UTF-8', // 字符集
    \TDengine\TSDB_OPTION_TIMEZONE => 'Asia/Shanghai', // 時(shí)區(qū)
    \TDengine\TSDB_OPTION_CONFIGDIR => '/etc/taos', // 配置目錄
    \TDengine\TSDB_OPTION_SHELL_ACTIVITY_TIMER => 3, // shell 活動(dòng)定時(shí)器
]);

// 獲取客戶端版本信息
var_dump(\TDengine\CLIENT_VERSION);
var_dump(\TDengine\getClientInfo());

// 以下值都是默認(rèn)值，不改可以不傳
$host = '127.0.0.1';
$port = 6030;
$user = 'root';
$pass = 'taosdata';
$db = null;

// 實(shí)例化
$connection = new Connection($host, $port, $user, $pass, $db);
// 連接
$connection->connect();
// 獲取連接參數(shù)
$connection->getHost();
$connection->getPort();
$connection->getUser();
$connection->getPass();
$connection->getDb();
// 獲取服務(wù)端信息
$connection->getServerInfo();
// 選擇默認(rèn)數(shù)據(jù)庫
$connection->selectDb('db1');
// 關(guān)閉連接
$connection->close();

查詢：

// 查詢
$resource = $connection->query($sql); // 支持查詢和插入
// 獲取結(jié)果集時(shí)間戳字段的精度，0 代表毫秒，1 代表微秒，2 代表納秒
$resource->getResultPrecision();
// 獲取所有數(shù)據(jù)
$resource->fetch();
// 獲取一行數(shù)據(jù)
$resource->fetchRow();
// 獲取字段數(shù)組
$resource->fetchFields();
// 獲取列數(shù)
$resource->getFieldCount();
// 獲取影響行數(shù)
$resource->affectedRows();
// 獲取 SQL 語句
$resource->getSql();
// 獲取連接對(duì)象
$resource->getConnection();
// 關(guān)閉資源（一般不需要手動(dòng)關(guān)閉，變量銷毀時(shí)會(huì)自動(dòng)釋放）
$resource->close();

參數(shù)綁定：

// 查詢
$stmt = $connection->prepare($sql); // 支持查詢和插入，參數(shù)用?占位
// 設(shè)置表名和標(biāo)簽
$stmt->setTableNameTags('表名', [
    // 支持格式同參數(shù)綁定
    [TDengine\TSDB_DATA_TYPE_INT, 36],
]);
// 綁定參數(shù)方法1
$stmt->bindParams(
    // [字段類型, 值]
    [TDengine\TSDB_DATA_TYPE_TIMESTAMP, $time1],
    [TDengine\TSDB_DATA_TYPE_INT, 36],
    [TDengine\TSDB_DATA_TYPE_FLOAT, 44.0],
);
// 綁定參數(shù)方法2
$stmt->bindParams([
    // ['type' => 字段類型, 'value' => 值]
    ['type' => TDengine\TSDB_DATA_TYPE_TIMESTAMP, 'value' => $time2],
    ['type' => TDengine\TSDB_DATA_TYPE_INT, 'value' => 36],
    ['type' => TDengine\TSDB_DATA_TYPE_FLOAT, 'value' => 44.0],
]);
// 執(zhí)行 SQL，返回 Resource，使用方法同 query() 返回值
$resource = $stmt->execute();
// 獲取 SQL 語句
$stmt->getSql();
// 獲取連接對(duì)象
$stmt->getConnection();
// 關(guān)閉（一般不需要手動(dòng)關(guān)閉，變量銷毀時(shí)會(huì)自動(dòng)釋放）
$stmt->close();

字段類型：

參數(shù)名稱	說明
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_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

在框架中使用

• imi 框架請看：imi-tdengine

tdengine-restful-connector

封裝了 TDengine 的 RESTful 接口，可以使用 PHP 輕松地操作 TDengine 的數(shù)據(jù)插入和查詢了。

此項(xiàng)目支持在 PHP >= 7.0 的項(xiàng)目中使用。

支持在 ThinkPHP、Laravel、Swoole、imi 等項(xiàng)目中使用

在 Swoole 環(huán)境中支持協(xié)程化，不會(huì)阻塞！

Github：https://github.com/Yurunsoft/tdengine-restful-connector

安裝

composer require yurunsoft/tdengine-restful-connector

使用

使用連接管理器：

// 增加名稱為 test 的連接配置
\Yurun\TDEngine\TDEngineManager::setClientConfig('test', new \Yurun\TDEngine\ClientConfig([
    // 'host'            => '127.0.0.1',
    // 'hostName'        => '',
    // 'port'            => 6041,
    // 'user'            => 'root',
    // 'password'        => 'taosdata',
    // 'db'              => 'database'
    // 'ssl'             => false,
    // 'timestampFormat' => \Yurun\TDEngine\Constants\TimeStampFormat::LOCAL_STRING,
    // 'keepAlive'       => true,
]));
// 設(shè)置默認(rèn)數(shù)據(jù)庫為test
\Yurun\TDEngine\TDEngineManager::setDefaultClientName('test');
// 獲取客戶端對(duì)象（\Yurun\TDEngine\Client）
$client = \Yurun\TDEngine\TDEngineManager::getClient();

直接 new 客戶端：

$client = new \Yurun\TDEngine\Client(new \Yurun\TDEngine\ClientConfig([
    // 'host'            => '127.0.0.1',
    // 'hostName'        => '',
    // 'port'            => 6041,
    // 'user'            => 'root',
    // 'password'        => 'taosdata',
    // 'db'              => 'database'
    // 'ssl'             => false,
    // 'timestampFormat' => \Yurun\TDEngine\Constants\TimeStampFormat::LOCAL_STRING,
    // 'keepAlive'       => true,
]));

// 通過 sql 方法執(zhí)行 sql 語句
var_dump($client->sql('create database if not exists db_test'));
var_dump($client->sql('show databases'));
var_dump($client->sql('create table if not exists db_test.tb (ts timestamp, temperature int, humidity float)'));
var_dump($client->sql(sprintf('insert into db_test.tb values(%s,%s,%s)', time() * 1000, mt_rand(), mt_rand() / mt_rand())));

$result = $client->sql('select * from db_test.tb');

$result->getResponse(); // 獲取接口原始返回?cái)?shù)據(jù)

// 獲取列數(shù)據(jù)
foreach ($result->getColumns() as $column)
{
    $column->getName(); // 列名
    $column->getType(); // 列類型值
    $column->getTypeName(); // 列類型名稱
    $column->getLength(); // 類型長度
}

// 獲取數(shù)據(jù)
foreach ($result->getData() as $row)
{
    echo $row['列名']; // 經(jīng)過處理，可以直接使用列名獲取指定列數(shù)據(jù)
}

$result->getStatus(); // 告知操作結(jié)果是成功還是失?。煌涌诜祷馗袷?
$result->getHead(); // 表的定義，如果不返回結(jié)果集，則僅有一列“affected_rows”。（從 2.0.17 版本開始，建議不要依賴 head 返回值來判斷數(shù)據(jù)列類型，而推薦使用 column_meta。在未來版本中，有可能會(huì)從返回值中去掉 head 這一項(xiàng)。）；同接口返回格式

$result->getRow(); // 表明總共多少行數(shù)據(jù)；同接口返回格式