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]