README

PHP的InfluxDB客户端库

概述

一个易于使用的库，用于使用PHP操作InfluxDB。由@thecodeassassin和@gianarb维护。

influxdb-php库的创建是为了使PHP能够使用Python的influxdb客户端。这样，就可以在不同的编程语言之间有一个共同的抽象库。

安装

可以使用composer进行安装

$ composer require shiveringpan/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的UDP。

时间戳精度

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

// 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');

待办事项

• 更多单元测试
• 增加文档（维基？）
• 向查询构建器添加更多功能
• 向 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 的获取器方法
• 支持Symfony 4

1.14.3

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

1.14.2

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

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的支持
• 向数据库->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