On 26/06/2025 17:53, Larry Garfield wrote:
Now here's the big one: Using enums rather than a bunch of constants is a good
change. However, I feel like it doesn't go far enough.
100% this.
Writing "$ch->setOptionInt(Curl\Option\IntOpt::ConnectTimeout, 30);"
instead of "curl_setopt(CURLOPT_CONNECTTIMEOUT, 30);" is mostly
rearranging the punctuation deck-chairs on the ugly code Titanic.
Particularly when you can *also*
write "$ch->setOptionInt(Curl\Option\IntOpt::ConnectTimeoutMs, 30_000);"
with the same effect.
I realize that would be considerably more work to define all those methods (I
don't even know how many Curl has, as I rarely use it directly).
I believe there are 272 "CURLOPT_" constants currently documented in the
PHP manual: https://www.php.net/manual/en/curl.constants.php
So, I totally agree that we need a "set raw option" method to support
some of the more niche features.
But that long list is also exactly why we badly need helpers for common
use cases - the manual page for curl_setopt has been at the top of the
charts for number of user comments for years, because nobody wants to
read the descriptions for two hundred options they'll never need.
On 26/06/2025 18:21, Eric Norris wrote:
I know that in the prior discussion, Rowan Tommins had a vision for a
high-level API (https://externals.io/message/122371#122424)
I think calling it a "vision for a high-level API" is making it sound
far more grandiose than what I suggested. What I suggested, and would
still like to see, is a small number of additional methods, for setting
really common options in a more user-friendly way.
Looking at my earlier message, my finger-in-the-air number was even
smaller than Larry's - a set of 10 methods, each covering a handful of
overlapping or closely related options.
A single "setHttpMethod" method would bring immediate value, instead of
choosing between CURLOPT_HTTPGET, CURLOPT_POST, CURLOPT_PUT,
CURLOPT_NOBODY (for HEAD) and CURLOPT_CUSTOMREQUEST.
Adding more helpers in later versions is entirely trivial, but we could
set the precedent with a first batch on day one.
The only other "high-level" API I see discussed in the previous thread
is splitting the execute() method, for exactly the same reason as
splitting setOpt(): type safety.
public function executeAndReturn(): string
public function executeAndOutput(): void
public function executeToFile(Stream $fileHandle): void
public function executeWithCallback(callable $wrIteFunction): void
The CURLOPT_RETURNTRANSFER, CURLOPT_FILE, and CURLOPT_WRITEFUNCTION
would then not exist in the option enum(s), because there would be no
way to make use of them.
Unlike the helper methods, that's one we have to decide in advance - it
would be a mess to have those *as well as* a universal "execute(): ?string".
--
Rowan Tommins
[IMSoP]
