CurlOne: Improved Observability Through Explicit Names

From: Michael via curl-and-php <curl-and-php_at_lists.haxx.se>
Date: Thu, 13 Aug 2026 23:45:05 +0500

Option Translation and Constant Overhead
----------------------------------------

To configure individual curl parameters by string
identifiers rather than raw integer values,
roughly 232 CURLOPT_* constants must be registered
during module startup[cite: 1]. These constants evaluate
to standard numeric identifiers in PHP userland[cite: 1].

The reverse lookup routine remains trivial:
options map back to registered internal
specification instances in the php-sm extension
layer[cite: 1]. Utilizing this structural mapping,
two standalone helpers handle runtime
introspection[cite: 1]:

  curl_getOptionName(int $option): string
  curl_getOptionNames(array $options): array

Primary utility centers on structured inspection
and dump-debugging within high-level transfer
wrappers[cite: 1]. Inspecting active configurations
yields readable key-value representations[cite: 1]:

  [
      "CURLOPT_URL" => "https://httpbin.org",
      "CURLOPT_TIMEOUT" => 10,
  ]

rather than uninformative numeric maps[cite: 1]:

  [
      10002 => "https://httpbin.org",
      13 => 10,
  ]

Although execution flow does not mandate these
inspection utilities, the scalar variant
_getOptionName serves internally to validate
values within option setters[cite: 1].

Duplicating this behavior purely in PHP
userland glue-code remains bad practice.
Relying on standard ext/curl wrappers
introduces duplicate symbol declarations and
unnecessary maintenance surface area, as manual
mirror definitions must constantly track native
extension updates[cite: 1].

-------------------------------------------------------

Handling Telemetry: CURLINFO_* Mapping
--------------------------------------

Managing CURLINFO_* parameters follows a
distinct pattern. The required constant set
is considerably smaller (~61 entries), and
batch queries from userland are unneeded[cite: 1].
Standard telemetry retrieval relies on
structured methods[cite: 1]:

  ⑴ getBasicInfo()
  ⑵ getInfo()
  ⑶ getCertInfo()

Calling getBasicInfo() builds a hashmap
pre-populated with string keys[cite: 1]. Using
numeric keys yields zero performance advantages
while significantly degrading runtime context
visibility during log analysis or execution
tracing[cite: 1].

Double types in CURLINFO_* are avoided
completely, storing measurements as 64-bit
integers instead. Additionally, no separate *_T
info constants are exposed; legacy PHP constant
names are retained while mapping directly to
underlying 64-bit integer values internally.

While stock ext/curl implementations supply
named keys when returning option maps, those
string identifiers are synthetic abstractions
rather than the true underlying native
CURLINFO_* constants[cite: 1]. Binding responses
directly to official constant names ensures
strict alignment with C-level libcurl
semantics[cite: 1].

-- 
curl-and-php mailing list
curl-and-php_at_lists.haxx.se
https://lists.haxx.se/mailman/listinfo/curl-and-php

Received on 2026-08-13