parse_url How to handle URLs with IPv6 addresses?

gitbox 2025-05-20

In PHP, parse_url is a common function used to break up URLs into their components, such as scheme, host, port, path, query, etc. This function is very practical in daily development, but when the URL contains an IPv6 address, its behavior will be slightly more complicated. This article will explore the behavior and precautions of parse_url when dealing with URLs containing IPv6 addresses.

How to represent IPv6 addresses in URLs

According to RFC 3986 , when the host part of a URL is an IPv6 address, it must be wrapped in square brackets. For example:

 http://[2001:db8::1]:8080/path?query=1

The purpose of square brackets is to separate from the colon of the port number and avoid parsing ambiguity.

Basic behavior of parse_url

The parse_url function syntax of PHP is as follows:

 parse_url(string $url, int $component = -1): array|string|false

When passing in a URL containing an IPv6 address, parse_url can correctly identify and extract the host part. Let’s take a look at a specific example:

 $url = 'http://[2001:db8::1]:8080/path?query=1';
$parts = parse_url($url);

print_r($parts);

The output result is:

 Array
(
    [scheme] => http
    [host] => 2001:db8::1
    [port] => 8080
    [path] => /path
    [query] => query=1
)

As you can see, although square brackets are used in the IPv6 address in the original URL, parse_url will remove square brackets in the return result, leaving only the pure address part. This is a behavior that suits expectations.

Example of error usage

If the IPv6 address is not wrapped correctly in square brackets in the URL, parse_url will not be parsed correctly. For example:

 $url = 'http://2001:db8::1:8080/path';
$parts = parse_url($url);

This code will return false because parse_url cannot determine whether 2001:db8::1:8080 is host or host plus port, resulting in syntax ambiguity.

summary

parse_url supports parsing URLs containing IPv6 addresses, provided that IPv6 addresses need to be wrapped in square brackets [] .
The host field in the return result does not contain square brackets.
If the IPv6 address is not wrapped in square brackets, parse_url will fail to parse and return false .
This function applies to most canonical URLs, but does not perform validity verification of the URL (for example, does not verify that the IP address is legal).

Practical advice

When using parse_url to process URLs (especially in scenarios where IPv6 addresses may be included), make sure that the input URL follows the RFC standard, especially the correct format for the host part. If it is a URL entered by the user, it is recommended to pre-process and verify the format before calling parse_url to avoid parsing failure or security issues.

parse_url