README

目录

• 关于
• 运行单个请求
  • 文件上传
  • 文件下载
• 运行多个异步请求
• 运行Cookie共享同步请求
  • 与HTTP Cookies协同工作
• 与响应协同工作
• 示例
  • HTTP GET请求
  • HTTP POST请求
  • HTTP PUT请求
  • HTTP DELETE请求
• 错误处理

关于

此API是一个轻量级cURL包装器，旨在通过一个功能齐全的OOP层完全隐藏底层的混乱本地库，该层易于使用且逻辑清晰。它是通过以下方式构建的，作为Guzzle（当今的“行业标准”）的对立面：

• 自给自足：与Guzzle不同，后者至少有40个依赖项，它只依赖于1个库进行单元测试
• 非常简单：每个类都旨在覆盖URL请求和响应处理的一个方面，但只有少数与开发者相关
• 非常快速：所有代码都在“少即是多”的范式下开发：没有过度抽象，没有超过严格需要的代码行

库的99%经过了单元测试（cURL功能的一些区域没有文档），完全符合PSR-4规范，仅需要PHP8.1+解释器和cURL扩展。安装时，您只需在控制台中写入以下内容

composer require lucinda/requester

然后使用提供的主要类之一

• Lucinda\URL\Request：封装单个通过cURL进行的HTTP/HTTPs请求（涵盖curl_*函数）
  • Lucinda\URL\FileUpload：专门针对文件上传对Lucinda\URL\Request进行优化
  • Lucinda\URL\FileDownload：专门针对文件下载对Lucinda\URL\Request进行优化
• Lucinda\URL\MultiRequest：封装通过cURL同时进行的多个HTTP/HTTPs请求（涵盖curl_multi_*函数）
• Lucinda\URL\SharedRequest：封装能够通过cURL共享cookie会话的多个HTTP/HTTPs请求（涵盖curl_share_*函数）

上述每个类都通过其方法分支到更深入的类，这些类根据请求的复杂性变得相关。每个请求的最终结果都是一个Lucinda\URL\Response对象，封装了所有响应信息（头、主体、状态）。

运行单个请求

执行单个HTTPS请求就像这样

$request = new Lucinda\URL\Request("https://www.lucinda-framework.com");
$response = $request->execute();

这会自动将目标主机内嵌的CAINFO证书与URL一起发送，以建立TLS连接，然后接收一个Lucinda\URL\Response对象。负责单个请求的类是Lucinda\URL\Request，定义了以下公共方法

文件上传

API 包含专门为文件上传设计的 Lucinda\URL\Request 扩展。要上传文件，您必须使用 Lucinda\URL\FileUpload，它包含以下附加的公共方法

示例（将 LOCAL_FILE_PATH 上传到 REMOTE_FILE_PATH）

$request = new Lucinda\URL\FileUpload(REMOTE_FILE_PATH);
$request->setMethod(Lucinda\URL\Request\Method::PUT);
$request->setFile(LOCAL_FILE_PATH);
$request->execute();

文件下载

API 包含专门为文件下载设计的 Lucinda\URL\Request 扩展。要下载文件，您必须使用 Lucinda\URL\FileDownload，它包含以下附加的公共方法

示例（将 REMOTE_FILE_PATH 下载到 LOCAL_FILE_PATH）

$request = new Lucinda\URL\FileDownload(REMOTE_FILE_PATH);
$request->setMethod(Lucinda\URL\Request\Method::GET);
$request->setFile(LOCAL_FILE_PATH);
$request->execute();

运行多个异步请求

同时执行多个请求并不复杂

$multiRequest = new Lucinda\URL\MultiRequest(Lucinda\URL\Request\Pipelining::HTTP2);
$multiRequest->add(new Lucinda\URL\Request("https://www.lucinda-framework.com/news"));
$multiRequest->add(new Lucinda\URL\Request("https://www.lucinda-framework.com/tutorials"));
$responses = $multiRequest->execute();

这同时执行两个请求，使用 HTTP2 管道并接收一个响应对象数组。负责单个请求的类是 Lucinda\URL\MultiRequest，定义以下公共方法

与原生的 curl_multi 不同，响应将按照请求池的顺序接收！执行将根据管道选项进行（请参阅构造函数）

• DISABLED：连接不进行管道化
• HTTP1：尝试在已建立的连接上对 HTTP/1.1 请求进行管道化
• HTTP2：如果 HTTP/2，则尝试在现有连接上多路复用新的传输
• HTTP1_HTTP2：尝试独立于彼此进行管道化和多路复用

运行 cookie 共享同步请求

要使多个请求共享 cookie/dns，就像这样简单

$sharedRequest = new Lucinda\URL\SharedRequest(Lucinda\URL\Request\ShareType::COOKIE);
$request1 = new Lucinda\URL\Request("http://www.example.com/page1");
$multiRequest->add($request1);
$request2 = new Lucinda\URL\Request("http://www.example.com/page1");
$multiRequest->add($request2);
$response1 = $request1->execute();
$response2 = $request2->execute();

这个文档记录得非常差的特性使第二个请求能够看到第一个请求中的 cookie。负责 cookie 共享请求的类是 Lucinda\URL\SharedRequest，定义以下公共方法

与运行请求的其他两个类不同，必须手动执行每个请求才能产生响应！Cookie 共享将根据共享类型选项进行（请参阅构造函数）

• COOKIES：连接将共享 HTTP cookie
• DNS：连接将共享缓存的 DNS 主机
• SSL_SESSION：连接将共享 SSL 会话 ID

与 HTTP cookie 一起工作

API 提供了一些用于与 cookie 一起工作的类，其领域在请求和响应之间

• Lucinda\URL\Cookies：实现基于 cURL 标准的一般 cookie 处理操作
• Lucinda\URL\Cookies\Cookie：实现单个 cookie 的逻辑（基于 HTTP set-cookie 报头标准）
• Lucinda\URL\Cookies\CookieParser：定义将 cookie 封装/解封装到/从中的接口
  • headers：通过 Lucinda\URL\Cookies\CookieHeader
  • files：通过 Lucinda\URL\Cookies\CookieFile

在日常使用中很少需要它们，因此要了解更多信息，请单击它们的链接查看文档。要了解它们如何使用，请检查相应的单元测试！

处理响应

每个成功请求（定义为收到任何响应的请求）的结果都封装在一个 Lucinda\URL\Response 对象中，该对象包含

• 响应状态：随响应一起到来的 HTTP 状态
• 响应头：与响应一起接收到的 HTTP 头
• 响应体：响应的实际内容（减去头和状态）
• 响应统计信息：由 API 或底层的 cURL 驱动程序提供（例如：总持续时间）

所有这些信息都可以通过以下公开方法查询：

示例

HTTP GET请求

# any request that doesn't *setMethod* is considered GET by default
$request = new Lucinda\URL\Request("https://www.example.com/?id=1");
$response = $request->execute();

HTTP POST请求

# any POST request MUST *setParameters*
$request = new Lucinda\URL\Request("https://www.example.com/add");
$request->setMethod(\Lucinda\URL\Request\Method::POST);
$request->setParameters(["asd"=>"fgh", "qwe"=>"rty"]);
$response = $request->execute();

HTTP PUT请求

# any PUT request MUST *setRaw* AND stringify parameters
$request = new Lucinda\URL\Request("https://www.example.com/edit");
$request->setMethod(\Lucinda\URL\Request\Method::PUT);
$request->setRaw(http_build_query(["id"=>1, "qwe"=>"tyu"]));
$response = $request->execute();

HTTP DELETE请求

# any DELETE request MUST *setRaw* AND stringify parameters
$request = new Lucinda\URL\Request("https://www.example.com/delete");
$request->setMethod(\Lucinda\URL\Request\Method::DELETE);
$request->setRaw(http_build_query(["id"=>1]));
$response = $request->execute();

错误处理

以下异常可能在API的请求-响应过程中抛出：

• Lucinda\URL\Request\Exception：如果在发送请求之前请求处理中发生错误（请求无效），则抛出。由该API定义的逻辑错误会抛出此异常。
• Lucinda\URL\Response\Exception：如果在发送请求之后接收响应时发生错误（例如：目标主机未响应），则抛出（涵盖curl_err和curl_multi_err函数）
• Lucinda\URL\FileNotFoundException：如果请求引用了一个不存在的本地文件。

一些观察

• 不支持curl_share_err错误，在PHP cURL文档以及它所封装的C库中都没有关于它的零文档。
• 只要接收到请求的响应，就不会抛出异常！API默认不将状态码如404或500视为错误，因此开发者需要决定如何处理它们。