README

InfluxDB的PHP客户端库

概览

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

创建influxdb-php库是为了有一个PHP版的Python influxdb客户端。这样，将会有一个不同编程语言之间的通用抽象库。

安装

可以使用composer进行安装

$ composer require influxdb/influxdb-php

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

如果您使用PHP 5.3或PHP 5.4，则0.1.x版本仍然受支持（修复bug和新版本修复）。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();

读取

要从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)
	->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;

写入数据

通过向数据库的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');

待办事项

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

变更日志

###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