clue / mdns-react
Simple, async multicast DNS (mDNS) resolver for zeroconf networking, built on top of ReactPHP.
Installs: 2 564
Dependents: 0
Suggesters: 0
Security: 0
Stars: 15
Watchers: 4
Forks: 6
Open Issues: 2
Requires
- php: >=5.3
- clue/multicast-react: ~1.0|~0.2.0
- react/dns: ~0.4.0|~0.3.0
- react/event-loop: ~0.4.0|~0.3.0
- react/promise: ^2.1 || ^1.2.1
This package is auto-updated.
Last update: 2024-10-08 17:11:39 UTC
README
Simple, async multicast DNS (mDNS) resolver for zeroconf networking, built on top of ReactPHP.
Multicast DNS name resolution is commonly used as part of zeroconf networking. It is used by Mac OS X (Bonjour), many Linux distributions (Avahi) and quite a few other networking devices such as printers, camers etc. to resolve hostnames of your local LAN clients to IP addresses.
This library implements the mDNS protocol as defined in RFC 6762. Note that this protocol is related to, but independent of, DNS-Based Service Discovery (DNS-SD) as defined in RFC 6763.
Table of Contents
Note: This project is in beta stage! Feel free to report any issues you encounter.
Quickstart example
Once installed, you can use the following code to look up the address of a local domain name:
<?php require __DIR__ . '/vendor/autoload.php'; $factory = new Clue\React\Mdns\Factory(); $resolver = $factory->createResolver(); $resolver->resolve('hostname.local')->then(function ($ip) { echo 'Found: ' . $ip . PHP_EOL; }, function (Exception $e) { echo 'Error: ' . $e->getMessage() . PHP_EOL; });
See also the examples.
Usage
Factory
The Factory
is responsible for creating your Resolver
instance.
$factory = new 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.
createResolver()
The createResolver()
method can be used to create a mDNS resolver instance that sends multicast DNS queries and waits for incoming unicast DNS responses. It returns a Resolver
instance.
$resolver = $factory->createResolver();
Resolver
The Factory
creates instances of the React\Dns\Resolver\Resolver
class from the react/dns package.
While ReactPHP's normal DNS resolver uses unicast UDP messages (and TCP streams) to query a given nameserver, this resolver instance uses multicast UDP messages to query all reachable hosts in your network.
Promises
Sending queries is async (non-blocking), so you can actually send multiple DNS queries in parallel. The mDNS hosts will respond to each DNS query message with a DNS response message. The order is not guaranteed. Sending queries uses a Promise-based interface that makes it easy to react to when a query is fulfilled (i.e. either successfully resolved or rejected with an error):
$resolver->resolve($hostname)->then( function ($ip) { // IP successfully resolved }, function (Exception $e) { // an error occurred while looking up the given hostname } });
Please refer to the DNS documentation for more details.
Blocking
As stated above, this library provides you a powerful, async API by default.
If, however, you want to integrate this into your traditional, blocking environment, you should look into also using clue/reactphp-block.
The resulting blocking code could look something like this:
<?php require __DIR__ . '/vendor/autoload.php'; use Clue\React\Block; $factory = new Clue\React\Mdns\Factory(); $resolver = $factory->createResolver(); $promise = $resolver->resolve('me.local'); try { $ip = Block\await($promise, $loop); // IP successfully resolved } catch (Exception $e) { // an error occurred while performing the request }
Similarly, you can also process multiple lookups concurrently and await an array of results:
$promises = array( $resolver->resolve('first.local'), $resolver->resolve('second.local'), ); $ips = Block\awaitAll($promises, $loop);
Please refer to clue/reactphp-block for more details.
Install
The recommended way to install this library is through Composer. New to Composer?
composer require clue/mdns-react:~0.2.0
See 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.
Tests
To run the test suite, you first need to clone this repo and then install all dependencies through Composer:
composer install
To run the test suite, go to the project root and run:
vendor/bin/phpunit
License
This 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.
More
- Multicast DNS is defined in RFC 6762, in particular this specification also highlights the differences to normal DNS operation.
- Please refer to the react/dns component for more details about normal DNS operation.