PHP gethostbyname() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Network

Definition

In PHP, gethostbyname() resolves a host name to a single IPv4 address string. On failure it returns the original hostname unchanged instead of false.

That failure behavior is easy to miss: always compare the result with the input name. If you need every IPv4 address, use gethostbynamel() which returns an array or false.

Syntax

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

PHP
$ip = gethostbyname("example.com");
CallWhat it does
gethostbyname("example.com")Returns an IPv4 address string such as "93.184.216.34".
gethostbyname("localhost")Usually returns "127.0.0.1" on local systems.
gethostbyname("no-such-host.invalid")Returns the same string on failure (hostname unchanged).

Success and failure both return a string. Detect failure with if ($ip === $hostname). This function returns only one address even when several exist.

Library declarations
PHP
gethostbyname(string $hostname): string

Parameters

ParameterDescription
hostnameRequired. The host name to resolve to an IPv4 address.

Return Value

Return ValueDescription
stringThe IPv4 address on success, or the original $hostname string unchanged on failure.

PHP Examples

Example 1 — Resolve a Host to One IPv4 Address

Look up example.com and print the address. The IP below is a typical sample.

PHP
<?php
$host = "example.com";
$ip = gethostbyname($host);
echo $ip;

How It Works

  1. Store the host name in $host.
  2. gethostbyname() asks DNS for one IPv4 address.
  3. Echo prints the address string.
  4. 93. 184.216.34 is a well-known sample for example.com.

Example 2 — Detect Failure Correctly

Compare the result with the original name so you can tell success from failure.

PHP
<?php
$host = "no-such-host.invalid";
$ip = gethostbyname($host);

if ($ip === $host) {
    echo "lookup failed", PHP_EOL;
} else {
    echo "ip=", $ip, PHP_EOL;
}

How It Works

  1. We use a name that should not resolve.
  2. On failure gethostbyname() returns the same string.
  3. Comparing with === detects that case.
  4. Do not use empty()—the failed result is still a non-empty string.

Example 3 — Resolve Localhost Offline

Resolve localhost, which usually works without public DNS.

PHP
<?php
$ip = gethostbyname("localhost");
echo $ip;

How It Works

  1. localhost is defined on almost every system.
  2. The usual IPv4 answer is 127. 0.0.1.
  3. This demo is offline-friendly for beginners.
  4. If your machine uses a different mapping, adjust expectations accordingly.

Frequently Asked Questions

It returns the original hostname string unchanged. Compare the result with the input to detect failure.
No. It returns only one IPv4 address. Use gethostbynamel() when you need the full list.
gethostbyname() is a simple name→IPv4 helper. dns_get_record() can fetch many DNS types with richer detail.
No. It is IPv4-only. For IPv6 data use dns_get_record() with DNS_AAAA or other IPv6-aware APIs.
Because both success and failure return strings. Equality with the original name is the documented failure signal.

Next: gethostbynamel()

gethostbynamel() resolves a host name to a list of IPv4 addresses. It returns an array of .

gethostbynamel() 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