Document DNS Query Options (constructor + getters/setters) in usage docs

docs/README.md

@@ -0,0 +1,78 @@
+# phpdns: PHP DNS Client Library
+
+## Overview
+
+The PHP DNS client is a GPL set of PHP classes originally developed by [David Cutting](https://davecutting.uk) providing a direct socket-level domain name service client API. Originally developed to be a testing module for the [FreeNATS network monitor](https://www.purplepixie.org/freenats/) it was decided to package it up as a standalone library as well.
+
+> Although there are plenty of other DNS classes/clients out there I found them to either be too overblown or actually non-functional. This API is intended to be a half-way house offering direct-to-server queries, the ability to process the response in detail but still with a simple interface for the programmer. -- *David Cutting*
+
+The library is now held at [github.com/purplepixie/phpdns](https://github.com/purplepixie/phpdns/) and contains contributions from a number of people both credited in the commits and prior to moving to Github.
+
+## Licence and Copyright
+
+Unless otherwise stated in a specific file the PHP DNS Query Library is (C) Copyright 2008-2023 [PurplePixie Systems / David Cutting](https://purplepixie.org) and all rights are reserved.
+
+The software is provided on an "as-is" basis without warranty or liability of any kind under the [GNU General Public Licence (GPL)](http://www.gnu.org/licences/gpl.html) (version 3 or later at your discretion).
+
+## Errors and Bugs
+
+Should be reported through raising an [issue on Github](https://github.com/purplepixie/phpdns/issues). You are also very welcome to contribute fixes to the code (or documentation) via a PR.
+
+# Installing / Obtaining phpdns
+
+There are two main ways to get phpdns: via composer or using the source code directly.
+
+## Composer
+
+By far the easiest way to use phpdns is through the use of [composer](https://getcomposer.org/) which allows you to use the latest release via [Packagist](https://packagist.org/packages/purplepixie/phpdns). With composer installed:
+
+```bash
+composer require purplepixie/phpdns
+``````
+
+Will install the latest release of phpdns which can then be used with autoload.
+
+You can now use the classes in the ```PurplePixie\PhpDns``` namespace through autoload, for example:
+
+```php
+// Autoload
+require("vendor/autoload.php");
+// Namespace for DNSQuery
+use PurplePixie\PhpDns\DNSQuery;
+// Do a query
+$query = new DNSQuery("8.8.8.8");
+$result = $query->query('purplepixie.org', \PurplePixie\PhpDns\DNSTypes::NAME_A);
+print_r($result);
+```
+
+## Using Source Directly
+
+You can just download and use the PHP source files directly, either by downloading an archive (this could be the [current codebase](https://github.com/purplepixie/phpdns/archive/refs/heads/master.zip) or a [specific release tag](https://github.com/purplepixie/phpdns/tags)) or by cloning [the repository](https://github.com/purplepixie/phpdns).
+
+To then use the library you must include the relevant files. You can do this manually or just include the ```dns.inc.php``` file (all this assumes you are above the ```src``` folder, otherwise you will need to adjust as required).
+
+Example of using source code manually:
+
+```php
+// Include the files - note: require_once 'dns.inc.php' will do this for you
+require_once __DIR__ . '/src/PurplePixie/PhpDns/DNSAnswer.php';
+require_once __DIR__ . '/src/PurplePixie/PhpDns/DNSQuery.php';
+require_once __DIR__ . '/src/PurplePixie/PhpDns/DNSResult.php';
+require_once __DIR__ . '/src/PurplePixie/PhpDns/DNSTypes.php';
+// Namespace for DNSQuery for ease
+use PurplePixie\PhpDns\DNSQuery;
+// Do a query
+$query = new DNSQuery("8.8.8.8");
+$result = $query->query('purplepixie.org', \PurplePixie\PhpDns\DNSTypes::NAME_A);
+print_r($result);
+```
+
+# Using phpdns
+
+For usage examples and instructions please see the [user documentation](./usage.md). There is also a [technical reference document](./technical.md).
+
+# Contributing to phpdns
+
+Contributions to phpdns are very welcome and the codebase is made stronger by the many contributions we have already seen. Feel free to contribute via Pull Requests in github for the main codebase or the documentation (main codebase is in the ```master``` branch and other dev branches, the docs are in the ```website``` branch).
+
+If you have found phpdns particularly useful then please feel free to give us a star on Github and if you're feeling financially generous make a donation to a charity of your choice (phpdns is *free* software in every sense).

docs/_config.yml

@@ -0,0 +1,16 @@
+lsi: false
+safe: true
+source: /docs
+incremental: false
+highlighter: rouge
+remote_theme: pages-themes/slate@v0.2.0
+plugins:
+- jekyll-remote-theme # add this line to the plugins list if you already have one
+gist:
+  noscript: false
+kramdown:
+  math_engine: mathjax
+  syntax_highlighter: rouge
+title: 'phpdns'
+description: 'PHP DNS Network Client'
+show_downloads: false

docs/examples.md

@@ -0,0 +1,87 @@
+### [<< Back to the main page <<](./)
+
+# phpdns Examples
+
+Here are some examples of phpdns being used. Please feel free to contribute to the documentation with specific interesting usage examples.
+
+## Recursive Resolution
+
+In normal operation phpdns will ask a single question of a given nameserver. This is fine when the nameserver is able to provide the answer (for example you have asked a local recursive resolver or an authoritative server for a zone) but is not representative of how DNS may actually work.
+
+A full recursive DNS resolution, for example as you see with ```dig +trace``` will start at the *root servers* and gradually work down. For example to resolve ```davecutting.uk``` A record the root servers won't know the answer but will provide the nameservers for .uk. The .uk nameservers won't know the answer but will know the next step, and so on.
+
+You can use phpdns to perform a full recursive search but you need to handle the recursive elements, it will only make the connections to each server in turn.
+
+Note in this example we start and continue to use *names* for the nameservers, so an internal DNS resolution is performed. We could once running add another step to use the additional section which usually provides glue records.
+
+```php
+<?php
+require("vendor/autoload.php");
+
+// Use namespaces for ease
+use PurplePixie\PhpDns\DNSQuery;
+use PurplePixie\PhpDns\DNSTypes;
+
+// Recursive function to work through NS records to type
+function DNSRecurse($question, $type, $server)
+{
+    echo "Query ".$question." ".$type." @ ".$server."\n";
+    $query = new DNSQuery($server);
+    $answer = $query->query($question, $type);
+    // error, stop here
+    if ($answer === false || $query->hasError())
+    {
+        echo "Error: ".$query->getLasterror()."\n";
+    }
+    else // successful query
+    {
+        if ($answer->count() > 0) // found an answer!
+        {
+            foreach($answer as $result)
+            {
+                echo $result->getString()." from ".$server."\n";
+            }
+        }
+        else // not found one - let's check the returned nameservers
+        {
+            $nameservers = $query->getLastnameservers();
+            if ($nameservers->count() == 0) // no route forward, exit
+            {
+                echo "No more nameservers returned.\n";
+            }
+            else // found a nameserver(s) to move on to
+            {
+                $ns = $nameservers->current();
+                $newserver = $ns->getData(); // get the nameserver
+                // and recurse
+                DNSRecurse($question, $type, $newserver);
+            }
+        }
+    }
+}
+
+// start with a list of nameservers
+$rootServers = array(
+    "a.root-servers.net",
+    "b.root-servers.net",
+    "c.root-servers.net",
+    "d.root-servers.net",
+    "e.root-servers.net",
+    "f.root-servers.net",
+    "g.root-servers.net",
+    "h.root-servers.net",
+    "i.root-servers.net" 
+);  
+
+// pick one at random
+$startServer = $rootServers[array_rand($rootServers)];
+
+echo "Starting from root server: ".$startServer."\n";
+
+// question and type we're asking
+$question = "www.purplepixie.org";
+$type = \PurplePixie\PhpDns\DNSTypes::NAME_A;
+
+// and kick the process off
+DNSRecurse($question, $type, $startServer);
+```

docs/technical.md

@@ -0,0 +1,7 @@
+### [<< Back to the main page <<](./)
+
+# phpdns Technical Documentation
+
+Technical documentation *may* be forthcoming but for the moment please just refer to the code itself and comments contained [in the repository](https://github.com/purplepixie/phpdns/).
+
+You may also find the [user documentation](./usage) and [examples](./examples) helpful.