Documentation and examples for advanced usage

README.md

@@ -13,6 +13,7 @@ easily be used to create a DNS server.
 * [Basic usage](#basic-usage)
 * [Caching](#caching)
   * [Custom cache adapter](#custom-cache-adapter)
+* [Advanced usage](#advance-usage)
 * [Install](#install)
 * [Tests](#tests)
 * [License](#license)
@@ -92,6 +93,31 @@ $dns = $factory->createCached('8.8.8.8', $loop, $cache);
 
 See also the wiki for possible [cache implementations](https://github.com/reactphp/react/wiki/Users#cache-implementations).
 
+## Advanced Usage
+
+For more advanced usages one can utilize the `Executor` directly.
+The following example looks up the `IPv6` address for `igor.io`.
+
+```php
+$loop = Factory::create();
+
+$executor = new Executor($loop, new Parser(), new BinaryDumper(), null);
+
+$executor->query(
+    '8.8.8.8:53', 
+    new Query($name, Message::TYPE_AAAA, Message::CLASS_IN, time())
+)->done(function (Message $message) {
+    foreach ($message->answers as $answer) {
+        echo 'IPv6: ' . $answer->data . PHP_EOL;
+    }
+}, 'printf');
+
+$loop->run();
+
+```
+
+See also the [fourth example](examples).
+
 ## Install
 
 The recommended way to install this library is [through Composer](http://getcomposer.org).

examples/04-query-a-and-aaaa.php

@@ -0,0 +1,32 @@
+<?php
+
+use React\Dns\Model\Message;
+use React\Dns\Protocol\BinaryDumper;
+use React\Dns\Protocol\Parser;
+use React\Dns\Query\Executor;
+use React\Dns\Query\Query;
+use React\EventLoop\Factory;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+
+$executor = new Executor($loop, new Parser(), new BinaryDumper(), null);
+
+$name = isset($argv[1]) ? $argv[1] : 'www.google.com';
+
+$ipv4Query = new Query($name, Message::TYPE_A, Message::CLASS_IN, time());
+$ipv6Query = new Query($name, Message::TYPE_AAAA, Message::CLASS_IN, time());
+
+$executor->query('8.8.8.8:53', $ipv4Query)->done(function (Message $message) {
+    foreach ($message->answers as $answer) {
+        echo 'IPv4: ' . $answer->data . PHP_EOL;
+    }
+}, 'printf');
+$executor->query('8.8.8.8:53', $ipv6Query)->done(function (Message $message) {
+    foreach ($message->answers as $answer) {
+        echo 'IPv6: ' . $answer->data . PHP_EOL;
+    }
+}, 'printf');
+
+$loop->run();