« Back to the main page «
phpdns User Documentation
Having successfully installed phpdns (if not see the “Installing / Obtaining phpdns” section of the main index page) you are now able to use it.
Note: This documentation assumes you have installed phpdns and are able to include it.
The phpdns library will on request make a network connection to a remote DNS server (using UDP or TCP) to ask a question (the query) and receive a response (an answer containing one or more results). The library consists of four main classes:
DNSQuery
- the primary class with which a user interfaces, builds and makes the actual query to the remote server.DNSAnswer
- a list/wrapper class containing theDNSResult
(s) from the remote server.DNSResult
- an actual result response from the remote server.DNSType
- a list of the types of DNS records that can be used in the query or in a result response.
A Simple Example
Here is a simple example to find an A record and output the result:
// Use this namespace for ease
use PurplePixie\PhpDns\DNSQuery;
// Remote DNS Server
$dnsServer = "8.8.8.8";
// The question we are going to ask for an answer to
$question = "www.purplepixie.org";
// The type of record/answer we are asking for
$type = \PurplePixie\PhpDns\DNSTypes::NAME_A;
try
{
// Create the DNSQuery instance for the remote server
$query = new DNSQuery($dnsServer);
// Perform an actual query for question and type
// note this will return a DNSAnswer instance
$answer = $query->query($question, $type);
// Check for an error
if ($answer === false || $query->hasError())
{
echo "Error: ".$query->getLasterror()."\n";
}
else // successful query
{
foreach($answer as $result)
{
// we are only after results of the type we want
if ($result->getType() == $type)
{
echo $question." has IP address ".$result->getData()."\n";
// or we can use the already built English string
echo $result->getString()."\n";
}
}
}
}
catch(\Exception $e)
{
print_r($e->getMessage());
}
If all goes well the output should be something like:
www.purplepixie.org has IP address 151.80.237.60
www.purplepixie.org has IPv4 address 151.80.237.60
The first output is from our script writing the question and the “data” result, the second when we output the “string” property of the answer which is the specific record in human-readable form (if the type is known).
A Note of Warning and Why Check the Answer Type Above
DNS is not an entirely straightforward protocol and things which on the surface may seem simple may not be when you delve deeper (if you already understand DNS then skip ahead).
For example an IP lookup (A record lookup) for a host on a specific DNS server may well not just return a single answer record containing the IP address. The host may be multi-honed and return multiple records any which may not be an IP address but a CNAME alias. The namesever you are querying may not do a recursive or cache lookup for you and so return no answers even though the domain and host do exist.
For this reason we must actually process the results (unless of course we just want to see what data is provided for a query and not actually do anything with that answer).
Hosts with just a CNAME alias will not be resolved to an IP address in the answer section. If we ask for the A record of www.somehost.com we may just get back a CNAME of webhost.somehost.com. To turn this into an IP address we must then either hope it was provided in the additional answer section (and check - see below for details) or perform another A record lookup on webhost.somehost.com.
If you just want an IP address for a host then either PHP’s inbuilt gethostbyname() or this API’s SmartALookup() (see below) are probably what you’re after rather than a full blown query.
Answer and Query Types
Record (query and result) types the API supports and should return sensible data for numerous and include the major record types such as A, NS, PTR, MX, CNAME, TXT and SOA. For a full list see the DNSTypes Class.
Asking for an unsupported type will cause the query to fail. Unsupported types which are returned as result records will have null “string” and “typeid” properties but will contain the binary data in “data” and the decimal record type in “type”.
Answer Results
If a query succeeds it returns an iteratable DNSAnswer
object containing zero or more DNSResult
objects with the specific answers. a counter property “count” indicating the number of answer records returned and an array of DNSResult objects containing each of these records in turn.
You can get a count of the results using DNSAnswer::count()
and either iterate using standard PHP iterations such as foreach
or accessing by numeric key.
Each DNSResult
object contains a lot of data, key items of which are:
DNSResult::getType()
- returns a textual version of the record type (i.e. “A”).DNSResult::getTypeid()
- returns the numeric record type which can be mapped toDNSType
if supported.DNSResult::getClass()
DNSResult::getData()
DNSResult::getDomain()
DNSResult::getString()
DNSResult::getExtras()
$answer->results[x]->typeid Textual record type ID (A, MX, CNAME etc) $answer->results[x]->type Numeric record type (decimal) $answer->results[x]->class Numeric class type (decimal) $answer->results[x]->data Data returned (i.e. IP address or hostname) $answer->results[x]->domain Domain name data is for $answer->results[x]->string String representation of the answer (i.e. www.fish.sea has address x.y.z) $answer->results[x]->extras Type-specific array of extra fields (i.e. “level” for MX exchanges) - see below
Type-specific Extras
Some result types have extended extra information which will be in array form in the “extras” property of a DNSResult
object.
MX record types for example have the decimal mail exchange priority in extas['level']
SOA record types have the responsible contact for the domain in extras['responsible']
as well as the following:
extras['serial']
- domain serialextras['refresh']
- domain refreshextras['retry']
- domain retryextras['expiry']
- domain expiryextras['minttl']
- domain mimumum time-to-live (TTL)
Smart A Lookup
Because doing an A lookup won’t always return an IP address and sometimes you’re just after an IP address (not potentially a list of them and aliases etc) the DNSQuery
class provides the DNSQuery::SmartALookup()
method.
This function simply takes a hostname and returns an IP address or a null string if lookup failed (you can then check the DNSQuery
error property to see if the query actually failed or just returned no results).
If the result data contains an IP address it will be returned (first preference). If no IP addresses were provided but an alias CNAME is given then this will be looked up (recursing up to a depth of five aliases; with requests to the same DNS server).
In effect this is a nameserver-specific version of gethostbyname() but returns a null string rather than the unmodified IP on failure.
Note: Smart A Lookup only works on a single server, if you want to do a recursive resolution to different nameservers you will need to do that yourself; see the example on the examples page.