PHP gethostbynamel() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Network

Definition

In PHP, gethostbynamel() resolves a host name to a list of IPv4 addresses. It returns an array of address strings, or false when the lookup fails.

Use it when a host may have several A records and you want every address, not just the first. For a single address string with the special failure behavior, see gethostbyname().

Syntax

Call gethostbynamel() with the values you need. Start with this line.

PHP
$ips = gethostbynamel("example.com");
CallWhat it does
gethostbynamel("example.com")Returns an array of IPv4 strings, or false on failure.
gethostbynamel("localhost")Often returns ["127.0.0.1"].
implode(", ", gethostbynamel("example.com") ?: [])Joins all addresses into one string, using [] when the lookup fails.

Unlike gethostbyname(), failure is false (not the original name). Always check the return type before looping. Addresses are IPv4 only.

Library declarations
PHP
gethostbynamel(string $hostname): array|false

Parameters

ParameterDescription
hostnameRequired. The host name to resolve.

Return Value

Return ValueDescription
arrayA list of IPv4 address strings associated with the host.
falseReturned when the host could not be resolved.

PHP Examples

Example 1 — List Every IPv4 Address

Resolve a host and print each address on its own line. Sample output shows one typical address.

PHP
<?php
$ips = gethostbynamel("example.com");

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

How It Works

  1. gethostbynamel() returns array|false.
  2. We handle false before looping.
  3. Each array item is an IPv4 string.
  4. The printed IP is a typical sample for example. com.

Example 2 — Failed Lookup Returns false

Show the failure value with var_dump() so it is not confused with an empty array.

PHP
<?php
$result = gethostbynamel("no-such-host.invalid");
var_dump($result);

How It Works

  1. The host name is intentionally invalid.
  2. gethostbynamel() returns false, not [].
  3. var_dump() makes the type obvious.
  4. Writing foreach ($result as . ..) without a check would error.

Example 3 — Count Addresses for Localhost

Resolve localhost offline and count how many IPv4 addresses were returned.

PHP
<?php
$ips = gethostbynamel("localhost");

if ($ips === false) {
    echo "0", PHP_EOL;
} else {
    echo count($ips), PHP_EOL;
    echo $ips[0], PHP_EOL;
}

How It Works

  1. localhost usually resolves without public DNS.
  2. count() shows how many addresses were returned.
  3. We print the first address for clarity.
  4. Your system might return more than one address; this sample shows the common case.

Frequently Asked Questions

An array of IPv4 address strings on success, or false if the host cannot be resolved.
gethostbynamel() returns every IPv4 address as an array (or false). gethostbyname() returns one address string, and on failure returns the hostname unchanged.
You probably did not check for false. Only loop when the return value is an array.
No. It is IPv4-only. Use dns_get_record() with DNS_AAAA for IPv6 addresses.
Normally each address appears once, but always treat the list as unordered DNS data and de-duplicate if your app needs a unique set.

Next: gethostname()

gethostname() returns the host name of the local machine running the script. On failure it.

gethostname() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful