sqmk/phue

Phue - Philips Hue PHP 客户端

维护者

详细信息

github.com/sqmk/Phue

主页

源代码

问题

安装量: 28,001

依赖项: 4

建议者: 0

安全: 0

星标: 203

关注者: 13

分支: 45

开放问题: 19

v1.7.1 2021-09-18 18:12 UTC

Requires

  • php: >=5.6.0

Requires (Dev)

Suggests

  • ext-curl: Allows usage of cURL transport adapter

BSD-3-Clause d3b68fc447cd596522cfedc1934f8dbb46d97ef9

  • Michael Squires <sqmk.woop@php.net>

clientphuephilipshue

This package is auto-updated.

Last update: 2024-09-19 01:12:46 UTC

README

Latest Stable Version Build Status

介绍

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 命令。该 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 扩展吗？

您的 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客户端中需要用到的。

如果提供的脚本找不到您的桥，或者您的网络中没有互联网连接，我创建了一个wiki页面，描述了寻找桥的其他几种方便的方法： 在网络上查找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 目录。