Simple, event-driven multicast UDP message client and server for ReactPHP.
Multicast UDP messages are needed for quite a few (low-level) networking protocols. Among others, multicast networking is the basis for mDNS (Multicast DNS), HTTPMU (Multicast UDP HTTP Messages), UPnP/SSDP (Universal Plug and Play / Simple Service Discovery Protocol) and others. This library exposes a simple subset of commonly needed functionality for multicast networking through an easy to use API.
Table of contents
I maintain an ecosystem of open-source projects that have been downloaded hundreds of millions of times and are actively maintained and continuously improved. If you find any of these projects useful, please consider becoming a sponsor on GitHub. Your support helps ensure long-term maintenance and continued development. Thank you! 🚀
Once installed, you can use the following code to create a simple echo server that listens for incoming multicast messages:
<?php
require __DIR__ . '/vendor/autoload.php';
$factory = new Clue\React\Multicast\Factory();
$socket = $factory->createReceiver('224.10.20.30:4050');
$socket->on('message', function ($data, $remote) use ($socket) {
echo 'Sending back ' . strlen($data) . ' bytes to ' . $remote . PHP_EOL;
$socket->send($data, $remote);
});See also the examples.
The Factory is responsible for creating your SocketInterface instances.
$factory = new Clue\React\Multicast\Factory();This class takes an optional LoopInterface|null $loop parameter that can be used to
pass the event loop instance to use for this object. You can use a null value
here in order to use the default loop.
This value SHOULD NOT be given unless you're sure you want to explicitly use a
given event loop instance.
The createSender(): SocketInterface method can be used to
create a socket capable of sending outgoing multicast datagrams and receiving
incoming unicast responses. It returns a SocketInterface instance.
$socket = $factory->createSender();
// send a multicast message to everybody listening on the given address
$socket->send('hello?', '224.10.20.30:4050');
// report incoming unicast replies
$socket->on('message', function ($data, $address) {
echo 'received ' . strlen($data) . ' bytes from ' . $address . PHP_EOL;
});This method works on PHP versions as old as PHP 5.3 (and up), as its socket API has always been level 1 multicast conformant.
The createReceiver(string $address): SocketInterface method can be used to
create a socket capable of receiving incoming multicast datagrams and sending
outgoing unicast or multicast datagrams. It returns a SocketInterface instance.
$socket = $factory->createReceiver('224.10.20.30:4050');
// report incoming multicast messages
$socket->on('message', function ($data, $remote) use ($socket) {
echo 'Sending back ' . strlen($data) . ' bytes to ' . $remote . PHP_EOL;
// send a unicast reply to the remote
$socket->send($data, $remote);
});This method requires PHP 5.4+ and ext-sockets.
Otherwise, it will throw a BadMethodCallException.
This is a requirement because receiving multicast datagrams requires a
level 2 multicast conformant
socket API.
The required multicast socket options and constants have been added with PHP 5.4+.
These options are only available to the low level socket API (ext-sockets), not
to the newer stream based networking API.
Internally, this library uses a workaround to create stream based sockets and then sets the required socket options on its underlying low level socket resource. This is done because ReactPHP is built around the general purpose stream based API and has only somewhat limited support for the low level socket API.
The Factory creates instances of the React\Datagram\SocketInterface
from the react/datagram package.
This means that you can use all its normal methods like so:
$socket->send($message, $address);
$socket->on('message', function ($message, $address) { });
$socket->on('close', function() { });
$socket->pause();
$socket->resume();
$socket->end();
$socket->close();Please refer to the datagram documentation for more details.
The recommended way to install this library is through Composer. New to Composer?
This project follows SemVer. This will install the latest supported version:
composer require clue/multicast-react:^1.3See also the CHANGELOG for details about version upgrades.
This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM. It's highly recommended to use the latest supported PHP version for this project.
The createSender() method works on all supported platforms
without any additional requirements. However, the createReceiver()
method requires PHP 5.4 (or up) and ext-sockets. See above for more details.
To run the test suite, you first need to clone this repo and then install all dependencies through Composer:
composer installTo run the test suite, go to the project root and run:
vendor/bin/phpunitThe test suite is set up to always ensure 100% code coverage across all
supported environments (except createReceiver() on legacy PHP 5.3). If you
have the Xdebug extension installed, you can also generate a code coverage
report locally like this:
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-textThis project is released under the permissive MIT license.
Do you use this project in a commercial setting? Sponsoring with invoicing is available, contact me (@clue) for details.