From cbe273c3d20c12bc07c5d734381f02ae3648e23d Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Thu, 6 Jul 2017 21:22:39 +0200 Subject: [PATCH] Add documentation and update README --- .gitmodules | 3 ++ README.md | 13 +++++---- docs/.gitignore | 3 ++ docs/.shared | 1 + docs/Gemfile | 5 ++++ docs/_config.yml | 23 +++++++++++++++ docs/index.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 115 insertions(+), 6 deletions(-) create mode 100644 .gitmodules create mode 100644 docs/.gitignore create mode 160000 docs/.shared create mode 100644 docs/Gemfile create mode 100644 docs/_config.yml create mode 100644 docs/index.md diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..a586324 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs/.shared"] + path = docs/.shared + url = https://github.com/amphp/website-shared diff --git a/README.md b/README.md index ef73e4a..7db8e4b 100644 --- a/README.md +++ b/README.md @@ -19,22 +19,23 @@ composer require amphp/dns require __DIR__ . '/vendor/autoload.php'; +use Amp\Dns; use Amp\Loop; Loop::run(function () { - $githubIpv4 = (yield Amp\Dns\resolve("github.com", $options = ["types" => Amp\Dns\Record::A])); + $githubIpv4 = yield Dns\resolve("github.com", Dns\Record::A); var_dump($githubIpv4); - $googleIpv4 = Amp\Dns\resolve("google.com", $options = ["types" => Amp\Dns\Record::A]); - $googleIpv6 = Amp\Dns\resolve("google.com", $options = ["types" => Amp\Dns\Record::AAAA]); + $googleIpv4 = Amp\Dns\resolve("google.com", Dns\Record::A); + $googleIpv6 = Amp\Dns\resolve("google.com", Dns\Record::AAAA); - $firstGoogleResult = (yield Amp\Promise\first([$googleIpv4, $googleIpv6])); + $firstGoogleResult = yield Amp\Promise\first([$googleIpv4, $googleIpv6]); var_dump($firstGoogleResult); - $combinedGoogleResult = (yield Amp\Dns\resolve("google.com")); + $combinedGoogleResult = yield Amp\Dns\resolve("google.com"); var_dump($combinedGoogleResult); - $googleMx = (yield Amp\Dns\query("google.com", Amp\Dns\Record::MX)); + $googleMx = yield Amp\Dns\query("google.com", Amp\Dns\Record::MX); var_dump($googleMx); }); ``` diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..34f6bef --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +.bundle +_site +Gemfile.lock diff --git a/docs/.shared b/docs/.shared new file mode 160000 index 0000000..d13039f --- /dev/null +++ b/docs/.shared @@ -0,0 +1 @@ +Subproject commit d13039f87752ff36372ff8ea0687df376eba4f58 diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..ada6383 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,5 @@ +source "https://rubygems.org" +gem "github-pages" +gem "kramdown" +gem "jekyll-github-metadata" +gem "jekyll-relative-links" diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..2e768e3 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,23 @@ +kramdown: + input: GFM + toc_levels: 2..3 + +baseurl: "/dns" +layouts_dir: ".shared/layout" + +exclude: ["Gemfile", "Gemfile.lock", "README.md", "vendor"] +include: [".shared"] + +repository: amphp/dns +gems: + - "jekyll-github-metadata" + - "jekyll-relative-links" + +defaults: + - scope: + path: "" + type: "pages" + values: + layout: "docs" + +asset_path: "/dns/.shared/asset" diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..6a00343 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,73 @@ +--- +title: Asynchronous DNS Resolution +permalink: / +--- +`amphp/dns` provides asynchronous DNS name resolution for [Amp](http://amphp.org/amp). + +## Installation + +```bash +composer require amphp/dns +``` + +## Usage + +### Configuration + +`amphp/dns` automatically detects the system configuration and uses it. On Unix-like systems it reads `/etc/resolv.conf` and respects settings for nameservers, timeouts, and attempts. On Windows it looks up the correct entries in the Windows Registry and takes the listed nameservers. You can pass a custom `ConfigLoader` instance to `BasicResolver` to load another configuration, such as a static config. + +It respects the system's hosts file on Unix and Windows based systems, so it works just fine in environments like Docker with named containers. + +The package uses a global default resolver with can be accessed and changed via `Amp\Dns\resolver()`. If an argument other than `null` is given, the given resolver is used as global instance. The instance is automatically bound to the current event loop. If you replace the event loop via `Amp\Loop::set()`, then you have to set a new global resolver. + +Usually you don't have to change the resolver. If you want to use a custom configuration for a certain request, you just create a new resolver instance and use that instead of changing the global one. + +### Address Resolution + +`Amp\Dns\resolve` provides hostname to IP address resolution. It returns an array of IPv4 and IPv6 addresses by default. The type of IP addresses returned can be restricted by passing a second argument with the respective time. + +```php +// Example without type restriction. Will return IPv4 and / or IPv6 addresses. +// What's returned depends on what's available for the given hostname. + +/** @var Amp\Dns\Record[] $records */ +$records = yield Amp\Dns\resolve("github.com"); +``` + +```php +// Example with type restriction. Will throw an exception if there are no A records. + +/** @var Amp\Dns\Record[] $records */ +$records = yield Amp\Dns\resolve("github.com", Amp\Dns\Record::A); +``` + +### Custom Queries + +`Amp\Dns\query` supports the various other DNS record types such as `MX`, `PTR`, or `TXT`. It automatically rewrites passed IP addresses for `PTR` lookups. + +```php +/** @var Amp\Dns\Record[] $records */ +$records = Amp\Dns\query("google.com", Amp\Dns\Record::MX); +``` + +```php +/** @var Amp\Dns\Record[] $records */ +$records = Amp\Dns\query("8.8.8.8", Amp\Dns\Record::PTR); +``` + +### Caching + +The `BasicResolver` caches responses by default in an `Amp\Cache\ArrayCache`. You can set any other `Amp\Cache\Cache` implementation by creating a custom instance of `BasicResolver` and setting that via `Amp\Dns\resolver()`, but it's usually unnecessary. If you have a lot of very short running scripts, you might want to consider using a local DNS resolver with a cache instead of setting a custom cache implementation, such as `dnsmasq`. + +### Reloading Configuration + +The `BasicResolver` (which is the default resolver shipping with that package) will cache the configuration of `/etc/resolv.conf` / the Windows Registry and the read host files by default. If you wish to reload them, you can set a periodic timer that requests a background reload of the configuration. + +```php +Loop::repeat(60000, function () use ($resolver) { + yield Amp\Dns\resolver()->reloadConfig(); +}); +``` + +{:.note} +> The above code relies on the resolver not being changed. `reloadConfig` is specific to `BasicResolver` and is not part of the `Resolver` interface. You might want to guard the reloading with an `instanceof` check or manually set a `BasicResolver` instance on startup to be sure it's an instance of `BasicResolver`.