PHP gethostbyname() Function: Everything You Need to Know

When your code needs to know where a server actually lives on the network — to ping it, connect a socket, log the resolved address, or whitelist it — you start from a host name like example.com and ask DNS for its IP. PHP's gethostbyname() does exactly that: given a host name, it returns the corresponding IPv4 address as a string.

This chapter covers what the function returns, the gotcha that trips most developers (how it signals failure), and the patterns you actually use it with.

Syntax

gethostbyname(string $hostname): string

It takes a single parameter:

• $hostname — the host name to resolve, for example "www.example.com".

The function performs a DNS lookup (an A record query) and returns the first IPv4 address it finds, formatted as a dotted-quad string such as "93.184.216.34".

gethostbyname() resolves IPv4 (A records) only. There is no IPv6 equivalent in this family of functions — for AAAA records use dns_get_record() with the DNS_AAAA type.

Basic example

The function does a DNS lookup on "example.com" and prints a line like:

The IP address for host name example.com is 93.184.216.34

The exact IP can change over time and may differ by region, since it comes from live DNS.

The failure gotcha: it returns the host name unchanged

This is the single most important detail. gethostbyname() does not return false or throw on failure. When the lookup fails — the name does not exist, or DNS is unreachable — it returns the $hostname string you passed in, unchanged.

So you can't just check if ($ip). You have to check whether the result actually looks like an IP address:

<?php

$hostname = "this-host-does-not-exist.invalid";
$ip = gethostbyname($hostname);

if ($ip === $hostname) {
    echo "Could not resolve $hostname";
} else {
    echo "Resolved $hostname to $ip";
}

A more robust check is to validate the result with filter_var(), which works even in the rare case where the host name itself looks IP-like:

<?php

$hostname = "example.com";
$ip = gethostbyname($hostname);

if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
    echo "Resolved to a valid IPv4 address: $ip";
} else {
    echo "Resolution failed for $hostname";
}

Getting every address with gethostbynamel()

gethostbyname() returns only one address, even when a host name maps to several IPs (common for load-balanced services). To get the full list, use the sibling function gethostbynamel(), which returns an array of all IPv4 addresses:

<?php

$ips = gethostbynamel("example.com");

if ($ips === false) {
    echo "Lookup failed.";
} else {
    foreach ($ips as $ip) {
        echo $ip . PHP_EOL;
    }
}

Note that gethostbynamel() returns false on failure, unlike gethostbyname().

The reverse direction

If you already have an IP address and want the host name behind it, use the inverse function, gethostbyaddr():

<?php

$host = gethostbyaddr("93.184.216.34");
echo $host;

When to use it

• Resolving a configured host name to an IP before opening a low-level socket connection.
• Logging the resolved address alongside requests for auditing or rate-limiting.
• Quick connectivity or DNS sanity checks in scripts and health probes.

For richer DNS work — mail servers, all record types, TTLs — reach for dns_get_record(), checkdnsrr(), or dns_get_mx() instead.

Conclusion

gethostbyname() turns a host name into a single IPv4 address with one line of code. Remember its one quirk: on failure it hands the host name back to you rather than returning false, so always validate the result before trusting it. When you need every address, switch to gethostbynamel(); to go from IP back to name, use gethostbyaddr().

Practice