README

简介

Phue 是一个用于连接和管理 Philips Hue 照明系统的 PHP 客户端。

目前它在 Packagist 上注册，以便这个库可以轻松地包含在其他项目中。例如，有人可能希望将这个库与 Zend Framework 或 Symfony 打包在一起，以构建自己的 Hue 系统前端。

该客户端可以充分利用 Hue 的 API，包括

• 验证和管理用户
• 管理桥配置
• 管理灯光
• 管理组
• 管理传感器
• 管理传感器的规则
• 管理具有各种时间模式的日程
• 管理桥和灯光的软件更新
• 获取门户配置

对 API 文档感兴趣？您可以查看 Philips API 文档

需求

• PHP 5.6+
• cURL 扩展（可选）

对于 PHP 5.3 支持，请使用 Phue v1.6.x。

安装

Phue 库在 Packagist 上可用。您需要使用 composer 将 sqmk/phue 作为依赖项包含到您的项目中。如果您不熟悉 composer，请在此查看： Composer

您也可以在不使用 composer 的情况下使用此库。库目录是 library。您需要在您选择的自动加载程序中将命名空间 Phue 映射到此目录。

bin 和 examples 目录中的脚本依赖于 composer 的 vendor 目录中的类/命名空间映射器。您需要从此存储库的根目录运行 composer install 以使其工作。

安装所有包后，包含 composer 生成的自动加载器。自动加载器是 vendor/autoload.php。以下是从存储库根目录包含此文件的示例

<?php

require_once __DIR__ . '/vendor/autoload.php';

$client = new \Phue\Client('10.0.1.1', 'yourusername');

用法

对于所有示例，假设自动加载器已在您的 PHP 应用中某处包含。

首先，您需要实例化一个新的 Phue 客户端对象。您需要桥的 IP 地址和已验证的密钥/用户名。如果您不知道桥的 IP 地址或尚未验证用户，您可以使用 README 末尾记录的帮助脚本。

这是实例化客户端对象的示例

<?php

$client = new \Phue\Client('10.0.1.31', 'sqmk');

发布命令，测试连接和授权

您可以向桥发布 Ping 命令以测试向其发送请求。如果抛出 ConnectionException 异常，则与桥通信存在问题

try {
	$client->sendCommand(
		new \Phue\Command\Ping
	);
} catch (\Phue\Transport\Exception\ConnectionException $e) {
	echo 'There was a problem accessing the bridge';
}

在上面的示例中，您会注意到发送命令时，您需要实例化一个命令对象，然后使用 sendCommand 方法将命令传递给客户端。还有另一种更优雅地发送命令的方法。以下是另一种通过客户端向桥发送命令的方法

try {
	$ping = new \Phue\Command\Ping;
	$ping->send($client);
} catch (\Phue\Transport\Exception\ConnectionException $e) {
	echo 'There was a problem accessing the bridge';
}

所有命令都可以以类似于前两个示例的方式发布。

一旦确定可以向桥发送请求，您可以测试提供的用户名是否可用。

$isAuthenticated = $client->sendCommand(
	new \Phue\Command\IsAuthorized
);

echo $isAuthenticated
   ? 'You are authenticated!'
   : 'You are not authenticated!';

如果提供的用户名尚未创建，您可以使用方便的脚本进行验证，该脚本将在本 README 的后面记录。或者，您可以使用 CreateUser 命令自行完成。

// Push the bridge's link button prior to running this
try {
	$response = $client->sendCommand(
		new \Phue\Command\CreateUser
	);

	echo 'New user created: ' . $response->username;
} catch (\Phue\Transport\Exception\LinkButtonException $e) {
	echo 'The link button was not pressed!';
}

用户创建后，除非您重置网桥，否则无需再次创建！

管理灯光

现在您有了授权用户，可以开始使用客户端管理灯光。

有几种方法可以检索与网桥注册的灯光列表。您可以使用客户端提供的辅助方法，或者手动向客户端发送命令。这些命令返回一个包含 \Phue\Light 对象的数组

// From the client
foreach ($client->getLights() as $lightId => $light) {
	echo "Id #{$lightId} - {$light->getName()}", "\n";
}

// Or from command
$lights = $client->sendCommand(
	new \Phue\Command\GetLights
);

foreach ($lights as $lightId => $light) {
	echo "Id #{$lightId} - {$light->getName()}", "\n";
}

您也可以检索单个灯光。您可以通过客户端的 getLights 从灯光列表中取消引用，或者向客户端发送手动命令

// Retrieve light of id 3 from convenience method
$lights = $client->getLights();
$light = $lights[3];

echo $light->getName(), "\n";

// Manually send command to get light of id 3
$light = $client->sendCommand(
	new \Phue\Command\GetLightById(3)
);

echo $light->getName(), "\n";

没有灯光，或需要注册新灯泡？可以使用 StartLightScan 命令和 GetNewLights 命令来帮助注册新灯光。您可以通过查看位于此README末尾的 bin/phue-light-finder 脚本来了解这些命令的使用方法。

现在您可以检索 \Phue\Light 对象，可以使用客户端开始操作它们。以下是一些显示和更改灯光属性的示例

// Get a specific light
$lights = $client->getLights(); 
$light = $lights[3];

// Retrieving light properties:
echo $light->getId(), "\n",
     $light->getName(), "\n",
     $light->getType(), "\n",
     $light->getModelId(), "\n",
     $light->getSoftwareVersion(), "\n",
     $light->isOn(), "\n",
     $light->getAlert(), "\n",
     $light->getBrightness(), "\n",
     $light->getHue(), "\n",
     $light->getSaturation(), "\n",
     $light->getXY()['x'], "\n",
     $light->getXY()['y'], "\n",
     $light->getRGB()['red'], "\n",
     $light->getRGB()['green'], "\n",
     $light->getRGB()['blue'], "\n",
     $light->getEffect(), "\n",
     $light->getColorTemp(), "\n",
     $light->getColorMode(), "\n";

// Setting name
$light->setName('Living Room #1');

// Setting on/off state (true|false)
$light->setOn(true);

// Setting alert (select|lselect)
$light->setAlert('lselect');

// Setting brightness (0 for no light, 255 for max brightness)
$light->setBrightness(255);

// Set hue (0 to 65535), pairs with saturation, changes color mode to 'hs'
$light->setHue(56000);

// Set saturation (0 min, 255 max), pairs with hue, changes color mode to 'hs'
$light->setSaturation(255);

// Set xy, CIE 1931 color space (from 0.0 to 1.0 for both x and y)
// Changes color mode to 'xy'
$light->setXY(0.25, 0.5);

// Set rgb (0 to 255 each), is converted to XY and brightness
$light->setRGB(30, 100, 50);

// Set color temp (153 min, 500 max), changes color mode to 'ct'
$light->setColorTemp(300);

// Set effect (none|colorloop)
$light->setEffect('colorloop');

上面每个 set 方法都会向网桥发送一个请求。为了使用单个请求更新灯光的多个属性，应手动使用 SetLightState 命令。您还可以通过命令获得对 过渡时间 选项的访问权。

// Retrieve light
$lights = $client->getLights(); 
$light = $lights[3];

// Setting the brightness, hue, and saturation at the same time
$command = new \Phue\Command\SetLightState($light);
$command->brightness(200)
        ->hue(0)
        ->saturation(255);

// Transition time (in seconds).
// 0 for "snapping" change
// Any other value for gradual change between current and new state
$command->transitionTime(3);

// Send the command
$client->sendCommand(
    $command
);

管理组

网桥API允许您创建、更新和删除组。组对于同时控制多个灯光非常有用。

创建组很容易。您只需要一个名称，以及您想与该组关联的灯光列表（id，或 \Phue\Light 对象）

// Create group with list of ids, and get group
$groupId = $client->sendCommand(
	new \Phue\Command\CreateGroup('Office Lights', array(1, 2))
);

$groups = $client->getGroups(); 
$group = $groups[$groupId];

// Create group with list of lights, and get group
$groupId2 = $client->sendCommand(
	new \Phue\Command\CreateGroup(
		'Office Lights #2',
		array(
			$client->getLights()[1],
			$client->getLights()[2],
		)
	)
);

$groups = $client->getGroups(); 
$group = $groups[$groupId2];

有多种方法可以检索组。每种方法都返回一个包含 Phue\Group 对象的数组或单个实例

// Convenient way of retrieving groups
foreach ($client->getGroups() as $groupId => $group) {
	echo $group->getId(), ' - ',
	     $group->getName(), "\n";
}

// Manual command for retrieving groups
$groups = $client->sendCommand(
	new \Phue\Command\GetGroups
);

foreach ($groups as $groupId => $group) {
	echo $group->getId(), ' - ',
	     $group->getName(), "\n";
}

// Convenient way of retrieving a single group by id
$groups = $client->getGroups(); 
$group = $groups[1];

echo $group->getId(), ' - ',
     $group->getName(), "\n";

// Manual command for retrieving group by id
$group = $client->sendCommand(
	new \Phue\Command\GetGroupById(1)
);

echo $group->getId(), ' - ',
     $group->getName(), "\n";

大多数在 \Phue\Light 对象上可用的方法也在 \Phue\Group 对象上可用

// Get a specific group
$groups = $client->getGroups(); 
$group = $groups[1];

// Retrieving group properties:
echo $group->getId(), "\n",
     $group->getName(), "\n",
     implode(', ', $group->getLightIds()), "\n",
     $group->isOn(), "\n",
     $group->getBrightness(), "\n",
     $group->getHue(), "\n",
     $group->getSaturation(), "\n",
     $group->getXY()['x'], "\n",
     $group->getXY()['y'], "\n",
     $group->getRGB()['red'], "\n",
     $group->getRGB()['green'], "\n",
     $group->getRGB()['blue'], "\n",
     $group->getColorTemp(), "\n",
     $group->getColorMode(), "\n",
     $group->getEffect(), "\n";

// Setting name
$group->setName('Office');

// Setting lights
$lights = $client->getLights(); 
$group->setLights(array(
    $lights[1],
    $lights[2]
));

// Setting on/off state (true|false)
$group->setOn(true);

// Setting brightness (0 for no light, 255 for max brightness)
$group->setBrightness(255);

// Set hue (0 to 65535), pairs with saturation, changes color mode to 'hs'
$group->setHue(56000);

// Set saturation (0 min, 255 max), pairs with hue, changes color mode to 'hs'
$group->setSaturation(255);

// Set xy, CIE 1931 color space (from 0.0 to 1.0 for both x and y)
// Changes color mode to 'xy'
$group->setXY(0.25, 0.5);

// Set rgb (0 to 255 each), is converted to XY and brightness
$group->setRGB(30, 100, 50);

// Set color temp (153 min, 500 max), changes color mode to 'ct'
$group->setColorTemp(300);

// Set effect (none|colorloop)
$group->setEffect('colorloop');

与灯泡一样，\Phue\Group 对象上的每个 set 方法都会为每次调用发送一个请求。为了最小化调用次数并一次更改组上的多个属性，请使用 SetGroupState 命令。与 SetLightState 相同，SetGroupState 命令具有所有选项。

// Retrieve group
$groups = $client->getGroups(); 
$group = $groups[1];

// Setting the brightness, color temp, and transition at the same time
$command = new \Phue\Command\SetGroupState($group);
$command->brightness(200)
        ->colorTemp(500)
        ->transitionTime(0);

// Send the command
$client->sendCommand(
    $command
);

删除组也很简单。您可以从 \Phue\Group 对象中删除，或者发送一个命令

// Retrieve group and delete
$groups = $client->getGroups(); 
$group = $groups[1];
$group->delete();

// Send command
$client->sendCommand(
	new \Phue\Command\DeleteGroup(1)
);

有一个特殊的“所有”组，可以使用 GetGroupById 命令检索。该组通常包含所有关联的灯光。您可以通过将 id 0 传递给 GetGroupById 命令来检索此组

// Get all group
$allGroup = $client->sendCommand(
	new \Phue\Command\GetGroupById(0)
);

// Set brightness on all bulbs
$allGroup->setBrightness(255);

管理日程安排

网桥能够在指定时间处理调度命令。遗憾的是，日程安排不是重复的。网桥会在触发计划中的命令后删除日程安排。

可检索的命令将返回一个包含 \Phue\Schedule 对象的数组或单个实例。无法编辑日程安排，但允许删除。

// Create command to dim all lights
$groupCommand = new \Phue\Command\SetGroupState(0);
$groupCommand->brightness(30);

// Create schedule command to run 10 seconds from now
// Time is a parsable DateTime date.
$scheduleCommand = new \Phue\Command\CreateSchedule(
	'Dim all lights',
	'+10 seconds',
	$groupCommand
);

// Set a custom description on the schedule, defaults to name
$scheduleCommand->description('Dims all lights in house to 30');

// Send the schedule to bridge
$client->sendCommand($scheduleCommand);

// Show list of schedules
$command = $schedule->getCommand();
foreach ($client->getSchedules() as $scheduleId => $schedule) {
	echo $schedule->getId(), "\n",
	     $schedule->getName(), "\n",
	     $schedule->getDescription(), "\n",
	     $schedule->getTime(), "\n",
	     $command['address'], "\n",
	     $command['method'], "\n",
	     json_encode($command['body']), "\n";
}

// Delete a given schedule
$schedules = $client->getSchedules(); 
$schedule = $schedules[2];
$schedule->delete();

如果您在上面的示例中注意到，必须将 Actionable 命令传递给 CreateSchedule。唯一可执行的命令是

• SetLightState
• SetGroupState

没有cURL扩展？

您的PHP安装没有编译cURL扩展？您可以覆盖传输适配器并使用PHP的本地流功能。

// Instantiate a client object
$client = new \Phue\Client('10.0.1.1', 'yourusername');

// Override the default transport
$client->setTransport(
	new \Phue\Transport\Adapter\Streaming
);

其他命令

并非所有命令都已记录。您可以通过查看 library/Phue/Command/ 目录来查看所有可用的命令。

一些尚未记录的著名命令包括管理网桥本身。

• \Phue\Command\GetBridge
• \Phue\Command\SetBridgeConfig

示例/便利脚本

此包中包含一些脚本，它们既方便又提供了使用客户端的更多示例。

查找您的网桥

本包包含一个脚本 bin/phue-bridge-finder，该脚本可以帮助您在网络中查找您的Philips Hue桥。当您将桥连接到带有互联网连接的路由器时，桥会将信息发送到Philips的meethue服务器。桥将定期将其分配的网络IP地址和MAC地址发送给meethue。Philips meethue服务允许iPhone和Android应用直接从其服务器获取桥的列表，通过匹配来自您的请求设备和桥的IP地址。 bin/phue-bridge-finder使用相同的技巧。

在运行此脚本之前，请确保您的桥已开机并连接到您的路由器。桥上的所有灯都应点亮。

以下是运行此脚本的方法

$ ./bin/phue-bridge-finder

如果一切顺利，您将得到如下结果

Philips Hue Bridge Finder

Checking meethue.com if the bridge has phoned home:
  Request succeeded

Number of bridges found: 1
	Bridge #1
		ID: 001788fffe09dddd
		Internal IP Address: 10.0.1.31
		MAC Address: 00:17:88:09:dd:dd

结果中列出的内部IP地址就是您用于Phue客户端的地址。

如果提供的脚本找不到您的桥，或者您的网络没有互联网连接，我创建了一个维基页面，描述了其他几种方便的查找方法： 在网络上查找Philips Hue桥。

身份验证/创建用户

要测试连接并对桥进行身份验证，您可以使用bin/phue-create-user。该脚本使用Phue库发送请求并从Philips Hue桥接收响应。

到此，您应该已经准备好对桥进行身份验证了。桥将为您生成一个用户名。

以下是运行用于身份验证/创建用户的脚本的方法

$ ./bin/phue-create-user 10.0.1.31

如果连接正常，您将得到如下类似的响应

Testing connection to bridge at 10.0.1.31
Attempting to create user:
Press the Bridge's button!
Waiting.........

phue-create-user脚本将尝试每秒在桥上创建一个用户。在脚本运行时需要按桥的连接按钮（那个大圆形的亮灯按钮）。如果在脚本执行过程中按下按钮，您应该得到如下响应

Testing connection to bridge at 10.0.1.31
Attempting to create user:
Press the Bridge's button!
Waiting..........

Successfully created new user: abcdef0123456 

从那时起，您应该可以使用生成的用户名与Philips Hue桥进行交互！

扫描/注册新灯

现在您已经测试了连接和身份验证到桥，您现在可以使用Phue客户端注册您的灯。

已创建另一个方便的脚本，以演示如何使用Phue让桥开始扫描和检索新灯。此脚本名为phue-light-finder，也位于bin目录中。

您可以为phue-light-finder传递与phue-create-user相同的参数。以下是使用脚本的方法

$ ./bin/phue-light-finder 10.0.1.31 yourusername

以下是一些示例结果

Testing connection to bridge at 10.0.1.31
Scanning for lights. Turn at least one light off, then on...
Found: Light #1, Hue Lamp 1
Found: Light #2, Hue Lamp 2
Found: Light #3, Hue Lamp 3
Done scanning

现在您已经找到了并注册了新灯，您现在可以管理这些灯了！如果您在家里添加了额外的Hue灯，您可以使用Phue客户端和/或此脚本来调用扫描并检索它们。

更多示例

如果您想查看各种命令的示例，请查看examples目录。