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
We invest a lot of time developing, maintaining and updating our awesome open-source projects. You can help us sustain this high-quality of our work by becoming a sponsor on GitHub. Sponsors get numerous benefits in return, see our sponsoring page for details.
Let's take these projects to the next level together! 🚀
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.2See 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:
php vendor/bin/phpunitThis project is released under the permissive MIT license.
Did you know that I offer custom development services and issuing invoices for sponsorships of releases and for contributions? Contact me (@clue) for details.