语法种子/phue

Phue - Philips Hue PHP 客户端 - 由 SyntaxSeed 衍生 - 额外功能，错误修复。

维护者

详情

github.com/syntaxseed/Phue

主页

源代码

安装: 22

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

衍生: 45

v1.8.5 2022-04-22 14:42 UTC

Requires

  • php: 7.4.*|8.*

Requires (Dev)

Suggests

  • ext-curl: Allows usage of cURL transport adapter

BSD-3-Clause 00e775234fed0fc95d4b0500eb97f0c27abb6508

  • Michael Squires <sqmk.woop@php.net>
  • Jens Reinemuth <jens.woop@reinemuth.rocks>
  • Sherri Wheeler

clientphuephilipshue

This package is auto-updated.

Last update: 2024-09-22 19:36:53 UTC

README

Latest OrigStable Version

介绍

Phue 是一个用于连接和管理 Philips Hue 照明系统的 PHP 客户端。此包使用 Hue API 版本 1。

注意：此项目是 neoteknic/Phue 的分支，而 neoteknic/Phue 又是 sqmk/Phue 的分支。此文档可能包含错误的包名。

目前已在 Packagist 上注册，以便此库可以轻松地包含在其他项目中。例如，有人可能希望将此库与 Zend Framework 或 Symfony 结合使用，以构建自己的 Hue 系统前端。

客户端能够充分利用 Hue 的 API，包括

  • 认证和管理用户
  • 管理网桥配置
  • 管理灯光
  • 管理组
  • 管理传感器
  • 管理传感器的规则
  • 管理各种时间模式的计划
  • 管理网桥和灯光的软件更新
  • 获取门户配置

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

要求

  • PHP 7.1+, 8.0+
  • cURL 扩展（可选）

对于旧 PHP 支持，请使用由 sqmk/Phue 提供的原始包。

安装

Phue 库在 Packagist 中可用。您需要在项目中使用 composer 将 syntaxseed/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', 'yourbridgeusername');

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

您可以向网桥发送 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 目录。