PEAR Manual
Prev |  | Next

# Net_DNS_Resolver::query()

Net_DNS_Resolver::query() -- Queries a nameserver and returns a response

## Synopsis

    require_once('Net/DNS.php');

``Net_DNS_Packet Net_DNS_Resolver::query` (string $hostname [, string $type = 'A' [, string $class = 'IN']])`

## Description

- `hostname` - The name to lookup (eg. www.php.net)

- `type` - The record type to query

- `class` - The zone class to query

Constructs a DNS query packet and forwards the query to a nameserver configured in the system stub resolver (ie. /etc/resolv.conf). When a response is received from the DNS server, a fully populated Net_DNS_Packet object is returned that represents the response.

The resolver object contains many properties that control that behaviour of the resolver. Some of these settings are automatically read from the system resolver configuration if available. On Linux/UNIX based systems, this includes /etc/resolv.conf as well as various environment variables. This configuration is done at the time of object instantiation and can be overridden by setting the appropriate object properties.

This function will only return a Net_DNS_Packet if the ANSWER section contains resource records. Specifically, if the ANCOUNT variable in the DNS packet header is 0, query() will return 0 (note: 0, not FALSE). If you are expecting a packet without resource records in the ANSWER section, use Net_DNS_Resolver::rawQuery(). This is useful when doing manual recursion.

For a description of the returned RR data object, see Net_DNS_RR.

Resolver Configuration Object Properties:

- array $nameservers

  An array of nameserver IP addresses that should be queried.

- int $port

  The port on which nameservers should be queried. The default is 53.

- array $domain

  The domain in which the resolver client host resides.

- array $searchlist

  An array of strings containingg domains to apply to unqualified hosts passed to the resolver.

- int $retry

  The number of seconds between retransmission of unaswered queries

- int $retrans

  The number of times unanswered requests should be retried

- int $recurse

  Sets the value of the RD (recursion desired) bit in the header. If the RD bit is set to 0, the server will not perform recursion on the request.

- int $usevc

  Whether or not to use TCP (Virtual Circuits) instead of UDP If set to 0, UDP will be used unless TCP is required. TCP is required for questions or responses greater than 512 bytes.

- int $debug

  If set to TRUE (non-zero), debugging code will be displayed as the resolver makes the request.

Environment Variables:

- RES_NAMESERVERS

  Space separated list of nameserver IP addresses to query

- RES_SEARCHLIST

  Space separated list of domain names to add to unqualified search requests.

- LOCALDOMAIN

  The name of the domain

- RES_OPTIONS

  A space separated list of options formatted as:

  optionname:value

  If the value is ommited, the value defaults to 1 (true). [optionname] corresponds to an object property.

## Example

Example 48-1. Using Net_DNS_Resolver::query()
    <?php
    require_once 'Net/DNS.php';

    $resolver = new Net_DNS_Resolver();
    $response = $resolver->query('example.com');
    if ($response) {
      foreach ($response->answer as $rr) {
        $rr->display();
      }
    }
    ?>
Output:
    example.com.            129808  IN      A       192.0.34.166

The following example shows a DNS query for an MX record. Note that the IP address for the mail exchanger listed within the zone is returned with the response in the additional section. The second exchanger (that is not inside this zone) is not listed. To receive this address, you must perform another query specifically for the A record using the returned hostname.

Example 48-2. Using Net_DNS_Resolver::query() to look up an MX record
    <?php
    require_once 'Net/DNS.php';

    $resolver = new Net_DNS_Resolver();
    $response = $resolver->query('php.net', 'MX');
    if ($response) {
      foreach ($response->answer as $rr) {
        $rr->display();
      }
      if (count($response->additional)) {
        foreach ($response->additional as $rr) {
          $rr->display();
        }
      }
    }
    ?>
Output:
    php.net.                86121   IN      MX      15 smtp.osuosl.org.
    php.net.                86121   IN      MX      5 osu1.php.net.
    osu1.php.net.           86121   IN      A       140.211.166.39

The next example shows a more complex query with debugging information enabled. Note that the usevc option is set to TRUE. This forces the resolver to use TCP instead of UDP. This can be seen in the debug output on the send_tcp() line.

Example 48-3. Using Net_DNS_Resolver::query() with specific nameservers and options
    <?php
    require_once 'Net/DNS.php';

    $resolver = new Net_DNS_Resolver();
    $resolver->debug = 1; // Turn on debugging output to show the query
    $resolver->usevc = 1; // Force the use of TCP instead of UDP
    $resolver->nameservers = array(              // Set the IP addresses
                               '198.41.0.4',     // of the nameservers
                               '192.228.79.201'  // to query.
                               );
    $response = $resolver->query('example.com');
    if (! $response) {
      echo "\n";
      echo "ANCOUNT is 0, therefore the query() 'failed'\n";
      echo "See Net_DNS_Resolver::rawQuery() to receive this packet\n";
    }
    ?>
Output:
    ;; query(example.com, A, IN)
    ;; send_tcp(198.41.0.4:53)
    ;; sending 29 bytes
    ;; received 517 bytes
    ;; HEADER SECTION
    ;; id = 58298
    ;; qr = 1    opcode = QUERY    aa = 0    tc = 0    rd = 1
    ;; ra = 0    rcode  = NOERROR
    ;; qdcount = 1  ancount = 0  nscount = 13  arcount = 15

    ;; QUESTION SECTION (1 record)
    ;;
    ;example.com.   IN      A

    ;; ANSWER SECTION (0 records)

    ;; AUTHORITY SECTION (13 records)
    com.            172800  IN      NS      A.GTLD-SERVERS.NET.
    com.            172800  IN      NS      G.GTLD-SERVERS.NET.
    com.            172800  IN      NS      H.GTLD-SERVERS.NET.
    com.            172800  IN      NS      C.GTLD-SERVERS.NET.
    com.            172800  IN      NS      I.GTLD-SERVERS.NET.
    com.            172800  IN      NS      B.GTLD-SERVERS.NET.
    com.            172800  IN      NS      D.GTLD-SERVERS.NET.
    com.            172800  IN      NS      L.GTLD-SERVERS.NET.
    com.            172800  IN      NS      F.GTLD-SERVERS.NET.
    com.            172800  IN      NS      J.GTLD-SERVERS.NET.
    com.            172800  IN      NS      K.GTLD-SERVERS.NET.
    com.            172800  IN      NS      E.GTLD-SERVERS.NET.
    com.            172800  IN      NS      M.GTLD-SERVERS.NET.

    ;; ADDITIONAL SECTION (15 records)
    A.GTLD-SERVERS.NET.     172800  IN      AAAA    2001:503:a83e::2:30
    A.GTLD-SERVERS.NET.     172800  IN      A       192.5.6.30
    G.GTLD-SERVERS.NET.     172800  IN      A       192.42.93.30
    H.GTLD-SERVERS.NET.     172800  IN      A       192.54.112.30
    C.GTLD-SERVERS.NET.     172800  IN      A       192.26.92.30
    I.GTLD-SERVERS.NET.     172800  IN      A       192.43.172.30
    B.GTLD-SERVERS.NET.     172800  IN      AAAA    2001:503:231d::2:30
    B.GTLD-SERVERS.NET.     172800  IN      A       192.33.14.30
    D.GTLD-SERVERS.NET.     172800  IN      A       192.31.80.30
    L.GTLD-SERVERS.NET.     172800  IN      A       192.41.162.30
    F.GTLD-SERVERS.NET.     172800  IN      A       192.35.51.30
    J.GTLD-SERVERS.NET.     172800  IN      A       192.48.79.30
    K.GTLD-SERVERS.NET.     172800  IN      A       192.52.178.30
    E.GTLD-SERVERS.NET.     172800  IN      A       192.12.94.30
    M.GTLD-SERVERS.NET.     172800  IN      A       192.55.83.30

    ANCOUNT is 0, therefore the query() 'failed'
    See Net_DNS_Resolver::rawQuery() to receive this packet

## Note

This function can not be called statically.

Prev | Home | Next
Class Summary Net_DNS_Resolver | Up | Net_DNS_Resolver::rawQuery()