Download the PHP package syntaxseed/phue without Composer

Phue - Philips Hue client - fork by SyntaxSeed

Introduction

Phue is a PHP client used to connect to and manage the Philips Hue lighting system. This package uses the Hue API version 1.

NOTICE: This project is a fork of neoteknic/Phue which is in turn a fork of sqmk/Phue. This documentation may contain incorrect package names.

It is currently registered with Packagist so that this library can easily be included in other projects. For example, one may want to bundle this library with Zend Framework or Symfony to build their own front-end for the Hue system.

The client has the ability to make full use of the Hue's API, including:

• Authenticating and managing users
• Managing bridge configuration
• Managing lights
• Managing groups
• Managing sensors
• Managing rules for sensors
• Managing schedules with various time patterns
• Managing software updates to the bridge and lights
• Getting portal configuration

Interested in API docs? You can check out the Philips API documentation

Requirements

• PHP 7.1+, 8.0+
• cURL extension (optional)

For old php support please use the original package by sqmk/Phue.

Installation

The Phue library is available in Packagist. You'll want to include as a dependency in your project using composer. If you are not familiar with composer, check it out here: Composer

You can also use this library without composer. The library directory is . You'll want to map your namespace to this directory in your autoloader of choice.

The scripts in and are dependent on composer's class/namespace mapper within . You'll need to from root directory of this repo to get those working.

After all the packages are installed, include composer's generated autoloader. The autoloader is . An example of including this from the root directory of this repository:

Usage

For all examples, it is assumed that the autoloader is included somewhere in your PHP app.

To start, you'll need to instantiate a new Phue Client object. You'll need the IP of your bridge, and an authenticated key/username. If you don't know the IP of your bridge or haven't authenticated a user, you can use the helper scripts documented at the end of the README.

Here's how to instantiate a client object:

Issuing commands, testing connection and authorization

You can issue a Ping command to the bridge to test making a request to it. If a ConnectionException exception is thrown, then there is a problem with talking to the bridge:

In the above example, you'll notice that to send a command, you instantiate a command object, and then pass the command to the client using the method. There is also another way to send commands that may be a bit more elegant. Here is another way to issue commands to the bridge via the client:

All commands can be issued in a similar manner as the previous two examples.

Once you have determined you can make requests to the bridge, you can test if the username you provided is available.

If the username provided is not created, you can use the convenience script to authenticate, which is documented later in this README. Or, you can use the CreateUser command to do it yourself.

After the user is created, you won't have to create it again unless you reset the bridge!

Managing lights

Now that you have an authorized user, you can start managing the lights with the client.

There are a couple of ways to retrieve the list of lights that are registered with the bridge. You can use the helper method available from the client, or by manually issuing a command to the client. These commands return an array of objects:

You can also retrieve a single light. You can either dereference from the list of lights via from the client, or pass in a manual command to the client:

Don't have any lights, or need to register a new bulb? The command and the command can be used to help registering new lights. You can see how these commands are used by looking at the script, which is documented at the end of this README.

Now that you can retrieve objects, you can start manipulating them with the client. Here are a few examples of how to show and change a light's properties:

Each set method above issues a single request to the bridge. In order to update multiple attributes of a light with a single request, the command should be used manually. You also get access to the transition time option with the command.

Managing groups

The bridge API allows you to create, update, and delete groups. Groups are useful for controlling multiple lights at the same time.

Creating a group is easy. All you need is a name, and a list of lights (ids, or objects) that you want to associate with the group:

There are multiple ways of retrieving groups. Each way returns either an array or single instance of objects:

Most of the methods available on objects are also available on objects:

Just like the bulbs, each set method on the object will send a request for each call. To minimize calls and to change multiple properties on the group at once, use the command. The command has all the options as .

Deleting a group is also simple. You can either delete from the object, or issue a command:

There's a special "all" group that can be retrieved with the command. This group normally has all lights associated with it. You can retrieve this group by passing id 0 to the command:

Managing Schedules

The bridge has the ability to handle scheduling commands at a given time. Schedules, unfortunately, are not reoccurring. The bridge will delete a schedule once it fires the scheduled command.

Retrievable commands will return an array or single instance of a object. It is not possible to edit a schedule, but deleting is permitted.

If you noticed in the above example, a command must be passed to . The only commands that are actionable are:

Don't have the cURL extension?

Don't have the cURL extension compiled with your PHP install? You can override the transport adapter and use PHP's native streaming functions instead.

Other commands

Not all commands have been documented. You can view all the available commands by looking in the directory.

Some notable commands not yet documented include managing the bridge itself.

Example/convenience scripts

There are a few scripts included in this package which serve as both convenience and further examples of using the client.

Finding your Bridge

Included in this package is , a script that will help find your Philips Hue bridges on your network. When plugging in your bridge into your router with an internet connection, the bridge will phone home to Philips meethue servers. The bridge will periodically send its assigned network IP and MAC address to meethue. Philips meethue service allows iPhone and Android apps to pull a list of the bridges directly from their servers by matching IPs originating from your requesting devices and bridges. uses same technique.

Prior to running this script, make sure your bridge is powered up and linked to your router. All lights should be lit up on the bridge.

Here's how to run this script:

Assuming all goes well, you'll get results like this:

The internal IP address(es) listed in the results is what you need for the Phue client.

If the script provided doesn't find your bridge, or if you don't have internet connection on your network, I have created a wiki page that describes a few other convenient ways of finding it: Finding Philips Hue bridge on network.

Authentication / Creating a User

To test connectivity and authenticate with the bridge, you can use . The script uses the Phue library to make requests and receive responses from the Philips Hue bridge.

At this point, you should be ready to authenticate with the bridge. The bridge will generate a username for you.

Here's how to run the script for authenticating/creating a user:

If the connection is ok, you will get a response similar to this:

The script will attempt to create a user on the bridge once every second. The bridge's connection button (the big round lit up one) needs to be pressed while the script runs. If the button is pressed during execution of the script, you should get a response like this:

From then on, you should be able to use the username generated for interacting with the Philips Hue bridge!

Scanning / registering new lights

Now that you have tested connection and authentication to the bridge, you can now register your lights using the Phue client.

Another convenience script has been created to demonstrate how to use Phue to get the bridge to start scanning for and retrieving new lights. This script is , and it is also located in the directory.

You can pass the same arguments for as you did with . Here's how to use the script:

Example results are as follows:

Now that you have found and registered new lights with the bridge, you can now manage the lights! If you happen to add additional Hue lights to your home, you can use the Phue client and/or this script to invoke scanning and retrieving them.

More examples

If you are interested in seeing examples for all sorts of commands, check out the directory.