Thanks Rowan! > 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.
I apologize for misrepresenting your suggestion. I was mainly responding to your "the eventual aim should be that users don't need a userland wrapper" comment, which I worry sounds closer to what Ben was (I believe) objecting to - a higher-level wrapper. Upon re-reading though, I think that's potentially an unfair take - you did go on to say "...just to make a simple request in a readable 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. I'm not opposed to this, but I am - as previously stated - nervous about how and where we draw this line, since I expect there may be a lot of opinions here. That said, if the general consensus is that we want direct methods or properties for the N most common use-cases, I'm happy to make that change to the RFC. 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! > 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". 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.
