README

InfluxDB v1 客户端库通常由社区成员开发和维护。它们现在都已被 v2 客户端库所取代。正在存档以支持 v2 客户端库。请参阅 #171。

如果仍有此 v1 客户端库的用户，并且他们或其他人愿意至少保持其安全性更新，请通过 社区论坛 或 InfluxData Slack 联系。

influxdb-php

PHP 的 InfluxDB 客户端库

注意：此库用于与 InfluxDB 1.x 一起使用。要连接到 InfluxDB 2.x 实例，请使用 influxdb-client-php 客户端。

概述

这是一个易于使用的库，用于使用 PHP 与 InfluxDB 一起使用。由 @thecodeassassin、@gianarb 维护。

influxdb-php 库的创建是为了将 Python influxdb 客户端移植到 PHP。这样，将在不同的编程语言之间有一个共同的抽象库。

安装

可以使用 composer 进行安装

$ composer require influxdb/influxdb-php

注意：对于 PHP 5.3 和 PHP 5.4 用户

如果您使用的是 PHP 5.3 或 PHP 5.4，0.1.x 版本仍受支持（修复错误和新的发布修复）。0.1.x 分支将在 PHP 5.3 和 PHP 5.4 上运行，但不含 1.0.0 版本的所有功能，如 UDP 支持。

入门

初始化一个新的客户端对象

$client = new InfluxDB\Client($host, $port);

这将创建一个新的客户端对象，您可以使用它来读取和写入 InfluxDB 中的点。

也可以从 DSN（数据源名称）创建客户端

// directly get the database object
$database = InfluxDB\Client::fromDSN(sprintf('influxdb://user:pass@%s:%s/%s', $host, $port, $dbname));

// get the client to retrieve other databases
$client = $database->getClient();

重要：使用 DSN 时，请勿忘记对密码（以及用户名）进行 urlencode()（特别是如果它包含非字母数字字符）。否则可能会抛出异常。

读取数据

要从 InfluxDB 获取记录，可以直接在数据库上执行查询

// fetch the database
$database = $client->selectDB('influx_test_db');

// executing a query will yield a resultset object
$result = $database->query('select * from test_metric LIMIT 5');

// get the points from the resultset yields an array
$points = $result->getPoints();

还可以使用QueryBuilder对象。这是一个简化查询构建过程的类。

// retrieve points with the query builder
$result = $database->getQueryBuilder()
	->select('cpucount')
	->from('test_metric')
	->limit(2)
	->offset(2)
	->getResultSet()
	->getPoints();

// get the query from the QueryBuilder
$query = $database->getQueryBuilder()
	->select('cpucount')
	->from('test_metric')
	->where(["region = 'us-west'"])
	->getQuery();

在字符串上进行where查询时，请确保输入单引号；否则，InfluxDB将返回空结果。

您可以从客户端获取最后执行的查询。

// use the getLastQuery() method
$lastQuery = $client->getLastQuery();

// or access the static variable directly:
$lastQuery = Client::lastQuery;

使用超时读取数据

在生产环境中，如果您正在查询InfluxDB以生成对Web或API请求的响应，您可能希望为InfluxDB调用设置特定的超时，而不是默认的无限运行。

// Fetch the database using a 5 second time out
$database = InfluxDB\Client::fromDSN(sprintf('influxdb://user:pass@%s:%s/%s', $host, $port, $dbname), 5);

写入数据

通过向数据库的writePoints方法提供一个点的数组来执行写入数据。

// create an array of points
$points = array(
	new Point(
		'test_metric', // name of the measurement
		0.64, // the measurement value
		['host' => 'server01', 'region' => 'us-west'], // optional tags
		['cpucount' => 10], // optional additional fields
		1435255849 // Time precision has to be set to seconds!
	),
    new Point(
    	'test_metric', // name of the measurement
		0.84, // the measurement value
		['host' => 'server01', 'region' => 'us-west'], // optional tags
		['cpucount' => 10], // optional additional fields
		1435255849 // Time precision has to be set to seconds!
	)
);

// we are writing unix timestamps, which have a second precision
$result = $database->writePoints($points, Database::PRECISION_SECONDS);

在向InfluxDB写入度量时，可以添加多个字段。点类允许用户轻松地将数据批量写入influxDB。

度量的名称和值是必填的。额外的字段、标签和时间戳是可选的。InfluxDB默认使用当前时间作为时间戳。

您还可以在不指定值的情况下向度量写入多个字段。

$points = [
	new Point(
		'instance', // the name of the measurement
		null, // measurement value
		['host' => 'server01', 'region' => 'us-west'], // measurement tags
		['cpucount' => 10, 'free' => 1], // measurement fields
		exec('date +%s%N') // timestamp in nanoseconds on Linux ONLY
	),
	new Point(
		'instance', // the name of the measurement
		null, // measurement value
		['host' => 'server01', 'region' => 'us-west'], // measurement tags
		['cpucount' => 10, 'free' => 2], // measurement fields
		exec('date +%s%N') // timestamp in nanoseconds on Linux ONLY
	)
];

使用UDP写入数据

首先，将InfluxDB主机设置为支持传入UDP套接字。

[udp]
  enabled = true
  bind-address = ":4444"
  database = "test_db"

然后，在客户端中配置UDP驱动程序。

// set the UDP driver in the client
$client->setDriver(new \InfluxDB\Driver\UDP($client->getHost(), 4444));

$points = [
	new Point(
		'test_metric',
		0.84,
		['host' => 'server01', 'region' => 'us-west'],
		['cpucount' => 10],
		exec('date +%s%N') // this will produce a nanosecond timestamp on Linux ONLY
	)
];

// now just write your points like you normally would
$result = $database->writePoints($points);

或者简单地使用DSN（数据源名称）通过UDP发送指标。

// get a database object using a DSN (Data Source Name)
$database = \InfluxDB\Client::fromDSN('udp+influxdb://username:pass@localhost:4444/test123');

// write your points
$result = $database->writePoints($points);

注意：当使用UDP时，精度将被忽略。您应该始终在将数据写入InfluxDB时使用纳秒精度。

时间戳精度

在向点对象添加时间戳时提供正确的精度很重要。这是因为如果您指定了秒作为时间戳并且默认（纳秒）精度被设置，则输入的时间戳将是无效的。

// Points will require a nanosecond precision (this is default as per influxdb standard)
$newPoints = $database->writePoints($points);

// Points will require second precision
$newPoints = $database->writePoints($points, Database::PRECISION_SECONDS);

// Points will require microsecond precision
$newPoints = $database->writePoints($points, Database::PRECISION_MICROSECONDS);

请注意，在MacOS下，exec('date + %s%N')不适用；您可以使用PHP的microtime获取具有微秒精度的时间戳，如下所示

list($usec, $sec) = explode(' ', microtime());
$timestamp = sprintf('%d%06d', $sec, $usec*1000000);

创建数据库

在创建数据库时，会添加一个默认的保留策略。此保留策略没有持续时间，因此数据将与内存一起刷新。

此库在创建数据库时易于提供保留策略。

// create the client
$client = new \InfluxDB\Client($host, $port, '', '');

// select the database
$database = $client->selectDB('influx_test_db');

// create the database with a retention policy
$result = $database->create(new RetentionPolicy('test', '5d', 1, true));

// check if a database exists then create it if it doesn't
$database = $client->selectDB('test_db');

if (!$database->exists()) {
	$database->create(new RetentionPolicy('test', '1d', 2, true));
}

您还可以修改保留策略

$database->alterRetentionPolicy(new RetentionPolicy('test', '2d', 5, true));

并列出它们

$result = $database->listRetentionPolicies();

您还可以向数据库添加更多保留策略

$result = $database->createRetentionPolicy(new RetentionPolicy('test2', '30d', 1, true));

客户端函数

一些函数对于数据库来说过于通用。因此，这些函数在客户端中可用。

// list users
$result = $client->listUsers();

// list databases
$result = $client->listDatabases();

管理功能

您可以使用客户端的 $client->admin 功能通过API管理InfluxDB。

// add a new user without privileges
$client->admin->createUser('testuser123', 'testpassword');

// add a new user with ALL cluster-wide privileges
$client->admin->createUser('admin_user', 'password', \InfluxDB\Client\Admin::PRIVILEGE_ALL);

// drop user testuser123
$client->admin->dropUser('testuser123');

列出所有用户

// show a list of all users
$results = $client->admin->showUsers();

// show users returns a ResultSet object
$users = $results->getPoints();

授予和撤销权限

可以在数据库级别和集群范围内授予权限。要授予用户数据库上的特定权限，请提供数据库对象或数据库名称。

// grant permissions using a database object
$database = $client->selectDB('test_db');
$client->admin->grant(\InfluxDB\Client\Admin::PRIVILEGE_READ, 'testuser123', $database);

// give user testuser123 read privileges on database test_db
$client->admin->grant(\InfluxDB\Client\Admin::PRIVILEGE_READ, 'testuser123', 'test_db');

// revoke user testuser123's read privileges on database test_db
$client->admin->revoke(\InfluxDB\Client\Admin::PRIVILEGE_READ, 'testuser123', 'test_db');

// grant a user cluster-wide privileges
$client->admin->grant(\InfluxDB\Client\Admin::PRIVILEGE_READ, 'testuser123');

// Revoke an admin's cluster-wide privileges
$client->admin->revoke(\InfluxDB\Client\Admin::PRIVILEGE_ALL, 'admin_user');

待办事项

• 增加单元测试
• 增加文档（wiki？）
• 向查询构建器添加更多功能
• 向RetentionPolicy添加验证

变更日志

1.15.0

• 添加cURL驱动支持 #122（感谢 @aldas）
• 改进查询错误消息 #129（感谢 @andreasanta）

1.14.8

• 合并 #122

1.14.7

• 在QueryBuilder中添加偏移量（感谢 @lifekent 和 @BentCoder）

1.14.6

• 依赖更新 (#97)，由 @aldas 提供
• 添加超时信息。（#103），由 @NickBusey 提供
• 为guzzle添加指定connect_timeout的能力 (#105)，由 @brycefranzen 提供

1.14.5

• 更新关键概念链接以指向正确位置。
• 将昂贵的array_merge调用替换为foreach + array操作符
• 添加verifySSL的getter方法
• 支持Symfony 4

1.14.3

• 废弃数据库创建中的IF NOT EXISTS子句

1.14.2

• 修复在未提供用户名或密码时调用InfluxDB\Client::fromDSN时的Notice问题
• 修复了Guzzle客户端超时为浮点数的问题
• 修复了注释
• 删除未使用的属性
• 修复了拼写错误
• 修复了具有布尔/空值的标签触发解析错误

1.4.1

• 修复了问题：根据行协议转义字段值。

1.4.0

• 更新Influx数据库，支持写入直接有效载荷，感谢 @virgofx

1.3.1

• 添加将数据写入特定保留策略的能力，感谢 @virgofx !

1.3.0

• 在查询中添加对dbname的引号
• 添加orderBy到查询构建器
• 修复了错误的orderBy测试
• Travis容器基础设施和php 7

1.2.2

• 修复了listUsers()方法的问题
• 增加了更多的单元测试
• 向\InfluxDB\ResultSet添加getColumns方法

1.2.0

• 添加对32位系统的支持
• 为Point字段添加设置器/获取器

1.1.3

• 添加对symfony3的支持

1.1.2

• 修复了写入数据时的认证问题

1.1.1

• 添加对0.9.4的支持
• 在database->create()中添加if not exists支持
• 添加getLastQuery方法

1.1.0

• 添加对0.9.3 rc2的支持
• 更改了处理值的数据类型的方式
• 将保留策略列表更改为反映0.9.3中的更改

1.0.1

• 在guzzle驱动中添加了认证支持
• 添加了管理功能

1.0.0

• -重大变更- 停止支持PHP 5.3和PHP 5.4
• 允许自定义驱动
• UDP支持

0.1.2

• 在Database类中添加exists方法
• 在数据库类中添加时间精度

0.1.1

• 将存储库合并到influxdb/influxdb-php中
• 为createRetentionPolicy添加单元测试
• -重大变更- 修改了$client->db为$client->selectDB