PHP 8.1: Curl: DNS-over-HTTPS support

TypeNew Feature

In PHP 8.1, the Curl extension supports specifying a server for DNS-Over-HTTPS. It requires PHP to be compiled with libcurl version 7.62 or later.

Most of the current operating systems and distributions already support it, as they often include Curl 7.68 or later in Ubuntu 20.04, and other Linux/Windows/Mac OS operating systems.

A list of public DoH servers are available at Curl documentation.


The DNS-Over-HTTPS server URL is configured by setting the CURLOPT_DOH_URL option. This constant will only be available if the underlying libcurl version is >= 7.62.

$ch = curl_init('');
curl_setopt($ch, CURLOPT_DOH_URL, '');

The behavior of the CURLOPT_DOH_URL is exactly same as the libcurl behavior; see CURLOPT_DOH_URL explained.

DoH Server URL Validation

The entered server URL is not validated at the time it is set. It is validated when the Curl request is executed. It must be an HTTPS URL.

If the provided DNS server is not a valid URL, or does not return a valid response, the request will fail. There is no fall-back to system DNS resolver, or a default DoH server configured in Curl.

Unset DoH Server URL

To unset a previously configured DoH server URL, set its value to null.

curl_setopt($ch, CURLOPT_DOH_URL, null);

Note that the Curl handle's DNS cache is independent of DoH servers. Setting a different DoH server URL, or unsetting it will not clear the DNS cache, and Curl will reuse values previously returned by system DNS resolver or any of the DoH servers configured.

Backwards Compatibility Impact

This feature is only available on PHP 8.1 and later, and it is not possible to back-port this feature.

It is possible to explicitly set an IP address to a host with CURLOPT_RESOLVE option, if the caller obtains the DNS information by using a DoH server with its own DNS querying.

Cross-version compatibility can be achieved by checking the CURLOPT_DOH_URL constant:

$ch = curl_init();
if (defined('CURLOPT_DOH_URL')) {
    curl_setopt($ch, CURLOPT_DOH_URL, '');