Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127774
Feedback-ID: id5114917:Fastmail
Content-Type: multipart/alternative;
 boundary="------------Jc0M4j76nHhh9hHiUNj6WC8V"
Message-ID: <d953eb06-c600-4b61-bb22-c4b9312b3a45@rwec.co.uk>
Date: Fri, 27 Jun 2025 16:59:47 +0100
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Object-oriented curl API v2
Content-Language: en-GB
To: internals@lists.php.net
References: <CA+NMNO0K85acCismdBL=8vr5=nKg1_-i0BjXyiqnjoqGAnH3Xw@mail.gmail.com>
 <22a4327d-b27d-4e24-b07a-ae380fe8a0c4@app.fastmail.com>
 <efe58859-aa50-4cff-ad80-93712e1cc88f@rwec.co.uk>
 <CA+NMNO3DyYQSi6M4BwhbBhocu=2ToA5=6ZLYiQ5oXr1sUj7E5w@mail.gmail.com>
In-Reply-To: <CA+NMNO3DyYQSi6M4BwhbBhocu=2ToA5=6ZLYiQ5oXr1sUj7E5w@mail.gmail.com>
From: imsop.php@rwec.co.uk ("Rowan Tommins [IMSoP]")

This is a multi-part message in MIME format.
--------------Jc0M4j76nHhh9hHiUNj6WC8V
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit

On 27/06/2025 04:51, Eric Norris wrote:
> I can try to take a look at the curl options and do some github
> searches to see if I can identify common patterns. I agree that
> setting the HTTP method and timeout are good contenders. If someone
> else wants to propose a list as well, feel free!


For what it's worth, I grepped my work code base for "CURLOPT_", and 
grouped the results into the categories below. Some of these are 
definitely more "advanced" than others, and a lot could just be one 
helper covering the whole category.

Really basic (already in the proposed constructor):
CURLOPT_URL

Setting HTTP method:
CURLOPT_HTTPGET
CURLOPT_POST
CURLOPT_CUSTOMREQUEST

Request body (despite name, handles both form data and raw string bodies):
CURLOPT_POSTFIELDS

Request headers:
CURLOPT_HTTPHEADER
CURLOPT_USERAGENT
CURLOPT_ENCODING (deprecated in favour of CURLOPT_ACCEPT_ENCODING)

Response body handling:
CURLOPT_FILE
CURLOPT_RETURNTRANSFER

Response header handling (extremely fiddly; it would be AMAZING to have 
something like getLastResponseHeaders() returning an array):
CURLOPT_HEADER
CURLOPT_HEADERFUNCTION

Auth:
CURLOPT_HTTPAUTH
CURLOPT_USERPWD
CURLOPT_SSLCERT (there's also a CURLOPT_SSLCERT_BLOB)
CURLOPT_SSLKEY

Error and redirect handling:
CURLOPT_FOLLOWLOCATION
CURLOPT_FAILONERROR

Timeouts:
CURLOPT_CONNECTTIMEOUT
CURLOPT_TIMEOUT
CURLOPT_TIMEOUT_MS

Cookie handling:
CURLOPT_COOKIE
CURLOPT_COOKIEFILE
CURLOPT_COOKIEJAR

Connection parameter tuning:
CURLOPT_HTTP_VERSION
CURLOPT_SSLVERSION
CURLOPT_SSL_VERIFYPEER (common, but shouldn't be!)

Debug output (like response headers, this is very unintuitive for PHP 
users; $ch->enableVerboseLogs() and $ch->getVerboseLogs() would be very 
handy):
CURLOPT_VERBOSE
CURLOPT_CAINFO
CURLOPT_STDERR



> If we were to go this route, I would suggest:
>
> public function fetch(): string
> public function execute(resource|callable $out): void
>
> that is, one method to just return the contents of the URL, and
> another to either write output to a file (including STDOUT, if the
> user desires), or to send output to a write callback.


That makes a lot of sense! I've never been very good at keeping names 
and sentences short :)


-- 
Rowan Tommins
[IMSoP]

--------------Jc0M4j76nHhh9hHiUNj6WC8V
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <div class="moz-cite-prefix">On 27/06/2025 04:51, Eric Norris wrote:<span
      style="white-space: pre-wrap">
</span></div>
    <div class="moz-cite-prefix"><span style="white-space: pre-wrap">
</span></div>
    <div class="moz-cite-prefix"><span style="white-space: pre-wrap">
</span><span style="white-space: pre-wrap">
</span></div>
    <blockquote type="cite"
cite="mid:CA+NMNO3DyYQSi6M4BwhbBhocu=2ToA5=6ZLYiQ5oXr1sUj7E5w@mail.gmail.com">
      <pre wrap="" class="moz-quote-pre">I can try to take a look at the curl options and do some github
searches to see if I can identify common patterns. I agree that
setting the HTTP method and timeout are good contenders. If someone
else wants to propose a list as well, feel free!</pre>
    </blockquote>
    <p><br>
    </p>
    <p>For what it's worth, I grepped my work code base for "CURLOPT_",
      and grouped the results into the categories below. Some of these
      are definitely more "advanced" than others, and a lot could just
      be one helper covering the whole category.</p>
    <p>Really basic (already in the proposed constructor):<br>
      CURLOPT_URL<br>
      <br>
      Setting HTTP method:<br>
      CURLOPT_HTTPGET<br>
      CURLOPT_POST<br>
      CURLOPT_CUSTOMREQUEST<br>
      <br>
      Request body (despite name, handles both form data and raw string
      bodies):<br>
      CURLOPT_POSTFIELDS<br>
      <br>
      Request headers:<br>
      CURLOPT_HTTPHEADER<br>
      CURLOPT_USERAGENT<br>
      CURLOPT_ENCODING (deprecated in favour of CURLOPT_ACCEPT_ENCODING)<br>
      <br>
      Response body handling:<br>
      CURLOPT_FILE<br>
      CURLOPT_RETURNTRANSFER<br>
      <br>
      Response header handling (extremely fiddly; it would be AMAZING to
      have something like getLastResponseHeaders() returning an array):<br>
      CURLOPT_HEADER<br>
      CURLOPT_HEADERFUNCTION<br>
      <br>
      Auth:<br>
      CURLOPT_HTTPAUTH<br>
      CURLOPT_USERPWD<br>
      CURLOPT_SSLCERT (there's also a CURLOPT_SSLCERT_BLOB)<br>
      CURLOPT_SSLKEY</p>
    <p>Error and redirect handling:<br>
      CURLOPT_FOLLOWLOCATION<br>
      CURLOPT_FAILONERROR<br>
      <br>
      Timeouts:<br>
      CURLOPT_CONNECTTIMEOUT<br>
      CURLOPT_TIMEOUT<br>
      CURLOPT_TIMEOUT_MS<br>
      <br>
      Cookie handling:<br>
      CURLOPT_COOKIE<br>
      CURLOPT_COOKIEFILE<br>
      CURLOPT_COOKIEJAR<br>
      <br>
      Connection parameter tuning:<br>
      CURLOPT_HTTP_VERSION<br>
      CURLOPT_SSLVERSION<br>
      CURLOPT_SSL_VERIFYPEER (common, but shouldn't be!)<br>
      <br>
      Debug output (like response headers, this is very unintuitive for
      PHP users; $ch-&gt;enableVerboseLogs() and
      $ch-&gt;getVerboseLogs() would be very handy):<br>
      CURLOPT_VERBOSE<br>
      CURLOPT_CAINFO<br>
      CURLOPT_STDERR</p>
    <p><br>
    </p>
    <p><br>
    </p>
    <blockquote type="cite"
cite="mid:CA+NMNO3DyYQSi6M4BwhbBhocu=2ToA5=6ZLYiQ5oXr1sUj7E5w@mail.gmail.com">
      <pre wrap="" class="moz-quote-pre">If we were to go this route, I would suggest:

public function fetch(): string
public function execute(resource|callable $out): void

that is, one method to just return the contents of the URL, and
another to either write output to a file (including STDOUT, if the
user desires), or to send output to a write callback.
</pre>
    </blockquote>
    <p><br>
    </p>
    <p>That makes a lot of sense! I've never been very good at keeping
      names and sentences short :)</p>
    <p><br>
    </p>
    <pre class="moz-signature" cols="72">-- 
Rowan Tommins
[IMSoP]</pre>
  </body>
</html>

--------------Jc0M4j76nHhh9hHiUNj6WC8V--