PHP RFC: Object-oriented curl API v2

namespace Curl;
 
enum HandleOption: int {
    case AbstractUnixSocket = CURLOPT_ABSTRACT_UNIX_SOCKET;
    case AcceptEncoding     = CURLOPT_ACCEPT_ENCODING;
    case AcceptTimeoutMs    = CURLOPT_ACCEPTTIMEOUT_MS;
    // ...other options elided...
}

namespace Curl;
 
enum MultiHandleOption: int {
    case ChunkLengthPenaltySize   = CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE;
    case ContentLengthPenaltySize = CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE;
    case MaxConnects              = CURLMOPT_MAXCONNECTS;
    // ...other options elided...
}

namespace Curl;
 
enum Info: int {
    case AppConnectTime = CURLINFO_APPCONNECT_TIME;
    // ...other values elided...
}

namespace Curl;
 
enum Pause: int {
    case All = CURLPAUSE_ALL;
    // ...other values elided...
}

namespace Curl;
 
// "At the lowest level of the hierarchy there MUST be a base ``Exception`` and
// base ``Error`` defined within the top-level of the extension's namespace."
 
class CurlException extends \Exception {}
class CurlError extends \Error {}
 
// The HandleException class represents an exception generated by a Handle or MultiHandle.
class HandleException extends CurlException
{
    /** Equivalent to curl_error() or the non-existent curl_multi_error(). */
    protected string $message;
 
    /** Equivalent to curl_errno() or curl_multi_errno(). */
    protected int $code;
}

namespace Curl;
 
class Handle
{
    /** Equivalent to curl_errno(). */
    public private(set) int $errorNumber;
 
    /** Equivalent to curl_error(). */
    public private(set) string $errorMessage;
 
    /**
     * Equivalent to curl_init().
     */
    public function __construct(?string $uri = null);
 
    /**
     * Equivalent to curl_exec(), except it (a) throws exceptions on failure, and (b)
     * always returns the content as a string.
     * 
     * @throws \Curl\HandleException
     */    
    public function fetch(): string;
 
    /**
     * Equivalent to curl_exec(), except it (a) throws exceptions on failure, and (b)
     * will always write to the specified stream resource or write callback.
     * 
     * A callable must have the following signature:
     * 
     * callback(resource $curlHandle, string $data): int
     * 
     * curlHandle
     *   The cURL handle.
     * 
     * data
     *   The data to be written.
     * 
     * The data must be saved by the callback and the callback must return the exact
     * number of bytes written or the transfer will be aborted with an error.
     * 
     * @throws \Curl\HandleException
     */    
    public function execute(resource|callable $out): void
 
    /**
     * Equivalent to curl_getinfo().
     */    
    public function getInfo(?\Curl\Info $option): mixed;
 
    /**
     * Equivalent to curl_pause().
     */    
    public function pause(\Curl\Pause $flag): mixed;
 
    /**
     * Equivalent to curl_reset().
     */    
    public function reset(): void;
 
    /**
     * Equivalent to curl_setopt().
     * 
     * @throws \Curl\HandleException
     */    
    public function setOption(\Curl\HandleOption $opt, mixed $value): \Curl\Handle;
 
    /**
     * Equivalent to curl_escape().
     * 
     * @throws \Curl\HandleException
     */    
    public function escapeUrl(string $string): string;
 
    /**
     * Equivalent to curl_unescape().
     * 
     * @throws \Curl\HandleException
     */    
    public function unescapeUrl(string $string): string;
 
    /**
     * Equivalent to curl_upkeep().
     * 
     * @throws \Curl\HandleException
     */    
    public function upkeep(): void;
}

namespace Curl;
 
class MultiHandle
{
    /** Equivalent to curl_multi_errno(). */
    public private(set) int $errorNumber;
 
    /** Equivalent to curl_multi_error(), if it existed. */
    public private(set) string $errorMessage;
 
    /**
     * Equivalent to curl_multi_init().
     */
    public function __construct();
 
    /**
     * Equivalent to curl_multi_add_handle().
     * 
     * $out, if specified, will write the output of the Curl\Handle to the stream or callback
     * when the Curl\MultiHandle is executed. If not specified, you can retrieve the content of
     * the handle via the getContent() method.
     * 
     * @throws \Curl\HandleException
     */    
    public function addHandle(\Curl\Handle $handle, resource|callable|null $out = null): void;
 
    /**
     * Equivalent to curl_multi_remove_handle().
     * 
     * @throws \Curl\HandleException
     */    
    public function removeHandle(\Curl\Handle $handle): void;
 
    /**
     * Equivalent to curl_multi_exec(). Note that it will never return CURLM_CALL_MULTI_PERFORM, and will
     * internally emulate newer curl libraries. Returns true if there are still active connections.
     * 
     * @throws \Curl\HandleException
     */    
    public function execute(): bool;
 
    /**
     * Equivalent to curl_multi_getcontent().
     */    
    public function getContent(\Curl\Handle $handle): ?string;
 
    /**
     * Equivalent to curl_multi_info_read().
     */    
    public function getMessages(int &$queued_messages = null): array|false;
 
    /**
     * Equivalent to curl_multi_select().
     */    
    public function poll(float $timeout = 1.0): int
 
    /**
     * Equivalent to curl_multi_setopt().
     * 
     * @throws \Curl\HandleException
     */    
    public function setOption(\Curl\MultiHandleOption $opt, mixed $value): \Curl\MultiHandle;
}

<?php
 
$ch = new Curl\Handle("https://example.com")
    ->setOption(Curl\HandleOption::ConnectTimeout, 30)
    ->setOption(Curl\HandleOption::FollowLocation, true);
 
try {
    echo $ch->fetch() . "\n";
} catch (\Curl\HandleException $ex) {
    echo "curl error ($ex->code): $ex->message\n";
}

<?php
 
$ch = new Curl\Handle("https://example.com")
    ->setOption(Curl\HandleOption::ConnectTimeout, 30)
    ->setOption(Curl\HandleOption::FollowLocation, true);
 
$mh = new Curl\MultiHandle();
$mh->addHandle($ch);
 
while ($mh->execute()) {
    echo "multi handle is still active...\n";
    $mh->poll(1.0);
}
 
echo $mh->getContent($ch) . "\n";