PHP gethostbynamel() Function: Everything You Need to Know

As a PHP developer, you may need to obtain every IP address associated with a given host name, not just one. A single domain often resolves to multiple IP addresses for load balancing or redundancy. The built-in gethostbynamel() function handles this: it performs a DNS lookup and returns an array of all the IPv4 addresses behind that host name.

This page covers what gethostbynamel() returns, how it differs from the singular gethostbyname(), how to handle failures safely, and when you would reach for it.

What is the gethostbynamel() Function?

The gethostbynamel() function is a PHP built-in that retrieves a list of IPv4 addresses corresponding to a given Internet host name. The trailing l in the name stands for list — it is the array-returning sibling of gethostbyname(), which returns only a single address as a string.

Under the hood it issues a DNS A record lookup. A large site like google.com may publish several A records, so gethostbynamel() lets you see them all rather than just the first.

IPv4 only. gethostbynamel() returns IPv4 (A record) addresses exclusively. It will not return IPv6 (AAAA record) addresses. To inspect IPv6 or other record types, use dns_get_record() instead.

How to Use the gethostbynamel() Function

Using the gethostbynamel() function is straightforward. Here is the syntax:

The PHP syntax of gethostbynamel() Function

gethostbynamel(string $hostname): array|false

The function takes one parameter:

• $hostname: The host name for which you want to retrieve all IPv4 addresses (for example, "www.example.com").

Return Value

Returns a numerically indexed array of IPv4 address strings on success, or false if the host name could not be resolved.

Here is an example of how to use the gethostbynamel() function to retrieve all IP addresses associated with a host name:

How to Use the gethostbynamel() Function

In this example, we retrieve all IPv4 addresses associated with the host name "example.com". The function performs a DNS lookup and returns an array of addresses. We then loop through the array and display each one. Note the strict comparison !== false: this matters because an empty array is "falsy" but a failed lookup returns the boolean false, so checking for false explicitly is the safe, unambiguous test.

Expected Output

IP address for host name example.com is 93.184.216.34

The exact addresses you see depend on current DNS records and your network, so they may differ from the output above.

gethostbynamel() vs gethostbyname()

These two functions are easy to confuse. The difference is what they return:

A common pattern is to count how many addresses a host advertises:

<?php

$hostname = "example.com";
$addresses = gethostbynamel($hostname);

if ($addresses === false) {
    echo "Could not resolve $hostname\n";
} else {
    echo $hostname . " resolves to " . count($addresses) . " IPv4 address(es):\n";
    echo implode(", ", $addresses) . "\n";
}

Expected Output

example.com resolves to 1 IPv4 address(es):
93.184.216.34

When to Use gethostbynamel()

• Detecting multi-homed hosts. When a domain is served from several servers (round-robin DNS, a CDN), gethostbynamel() reveals the full set of addresses.
• Allowlisting / firewall rules. Resolve a host to all of its IPs before building an allowlist, so you don't miss one of the backends.
• Diagnostics and monitoring. Show every address a name resolves to when troubleshooting connectivity.

If you only need IPv6 support or other DNS record types (MX, TXT, CNAME), reach for dns_get_record() or checkdnsrr() instead.

Conclusion

The gethostbynamel() function retrieves the complete list of IPv4 addresses associated with a given host name, unlike gethostbyname(), which returns only one. By understanding its IPv4-only behavior, its false-on-failure return value, and proper error handling, you can safely integrate it into your PHP applications for DNS lookups, diagnostics, and allowlisting.

Practice