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目录中的脚本依赖于vendor中的composer类/命名空间映射器。您需要从此存储库的根目录运行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命令来帮助注册新灯。您可以通过查看文档末尾的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命令。SetGroupState命令具有与SetLightState相同的所有选项。

// 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扩展？

没有将cURL扩展编译到您的PHP安装中？您可以覆盖传输适配器，并使用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-create-user 相同的参数给 phue-light-finder。以下是使用脚本的方法

$ ./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 目录。