zlibproxy/vendor/yzh52521/easyhttp/README.md
2023-01-02 19:56:44 +08:00

342 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

EasyHttp 是一个轻量级、语义化、对IDE友好的HTTP客户端支持常见的HTTP请求、异步请求和并发请求让你可以快速地使用 HTTP 请求与其他 Web 应用进行通信。
> EasyHttp并不强制依赖于cURL如果没有安装cURLEasyHttp会自动选择使用PHP流处理或者你也可以提供自己的发送HTTP请求的处理方式。
如果您觉得EasyHttp对您有用的话别忘了给点个赞哦^_^
github:[github.com/yzh52521/easyhttp](https://github.com/yzh52521/easyhttp "github.com/yzh52521/easyhttp")
gitee:[gitee.com/yzh52521/easyhttp](https://gitee.com/yzh52521/easyhttp "gitee.com/yzh52521/easyhttp")
本包是基于 [ gouguoyin/easyhttp ](https://gitee.com/gouguoyin/easyhttp "gitee.com/gouguoyin/easyhttp") 进行扩展开发,主要实现了以下扩展:
1. 增加 retry() 重试机制。
2. 增加 debug 日志调试功能。
3. 增加 withHost 指定服务端base_url
# 安装说明
#### 环境依赖
- PHP >= 7.2.5
- 如果使用PHP流处理allow_url_fopen 必须在php.ini中启用。
- 如果使用cURL处理cURL >= 7.19.4并且编译了OpenSSL 与 zlib。
#### 一键安装
composer require yzh52521/easyhttp
## 发起请求
#### 同步请求
###### 常规请求
```php
$response = Http::get('http://httpbin.org/get');
$response = Http::get('http://httpbin.org/get?name=yzh52521');
$response = Http::get('http://httpbin.org/get?name=yzh52521', ['age' => 18]);
$response = Http::post('http://httpbin.org/post');
$response = Http::post('http://httpbin.org/post', ['name' => 'yzh52521']);
$response = Http::patch(...);
$response = Http::put(...);
$response = Http::delete(...);
$response = Http::head(...);
$response = Http::options(...);
```
###### 指定服务端base_url的请求
```php
// 指定服务端base_url地址,最终请求地址为 https://serv.yzh52521.com/login
$response = Http::withHost('https://serv.yzh52521.com')->post('/login');
```
###### 发送 Content-Type 编码请求
```php
// application/x-www-form-urlencoded(默认)
$response = Http::asForm()->post(...);
// application/json
$response = Http::asJson()->post(...);
```
###### 发送 Multipart 表单请求
```php
$response = Http::asMultipart(
'file_input_name', file_get_contents('photo1.jpg'), 'photo2.jpg'
)->post('http://test.com/attachments');
$response = Http::asMultipart(
'file_input_name', fopen('photo1.jpg', 'r'), 'photo2.jpg'
)->post(...);
$response = Http::attach(
'file_input_name', file_get_contents('photo1.jpg'), 'photo2.jpg'
)->post(...);
$response = Http::attach(
'file_input_name', fopen('photo1.jpg', 'r'), 'photo2.jpg'
)->post(...);
```
> 表单enctype属性需要设置成 multipart/form-data
###### 携带请求头的请求
```php
$response = Http::withHeaders([
'x-powered-by' => 'yzh52521'
])->post(...);
```
###### 携带重定向的请求
```php
// 默认
$response = Http::withRedirect(false)->post(...);
$response = Http::withRedirect([
'max' => 5,
'strict' => false,
'referer' => true,
'protocols' => ['http', 'https'],
'track_redirects' => false
])->post(...);
```
###### 携带认证的请求
```php
// Basic认证
$response = Http::withBasicAuth('username', 'password')->post(...);
// Digest认证(需要被HTTP服务器支持)
$response = Http::withDigestAuth('username', 'password')->post(...);
```
###### 携带 User-Agent 的请求
```php
$response = Http::withUA('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3100.0 Safari/537.36')->post(...);
```
###### 携带Token令牌的请求
```php
$response = Http::withToken('token')->post(...);
```
###### 携带认证文件的请求
```php
$response = Http::withCert('/path/server.pem', 'password')->post(...);
```
###### 携带SSL证书的请求
```php
// 默认
$response = Http::withVerify(false)->post(...);
$response = Http::withVerify('/path/to/cert.pem')->post(...);
```
###### 携带COOKIE的请求
```php
$response = Http::withCookies(array $cookies, string $domain)->post(...);
```
###### 携带协议版本的请求
```php
$response = Http::withVersion(1.1)->post(...);
```
###### 携带代理的请求
```php
$response = Http::withProxy('tcp://localhost:8125')->post(...);
$response = Http::withProxy([
'http' => 'tcp://localhost:8125', // Use this proxy with "http"
'https' => 'tcp://localhost:9124', // Use this proxy with "https",
'no' => ['.com.cn', 'yzh52521.cn'] // Don't use a proxy with these
])->post(...);
```
###### 设置超时时间(单位秒)
```php
$response = Http::timeout(60)->post(...);
```
###### 设置延迟时间(单位秒)
```php
$response = Http::delay(60)->post(...);
```
###### 设置并发次数
```php
$response = Http::concurrency(10)->promise(...);
```
###### 重发请求设置retry方法。重试次数/两次重试之间的时间间隔(毫秒):
```php
$response = Http::retry(3, 100)->post(...);
```
#### 异步请求
```php
use yzh52521\EasyHttp\Response;
use yzh52521\EasyHttp\RequestException;
Http::getAsync('http://easyhttp.yzh52521.cn/api/sleep3.json', ['token' => TOKEN], function (Response $response) {
echo '异步请求成功,响应内容:' . $response->body() . PHP_EOL;
}, function (RequestException $e) {
echo '异步请求异常,错误码:' . $e->getCode() . ',错误信息:' . $e->getMessage() . PHP_EOL;
});
echo json_encode(['code' => 200, 'msg' => '请求成功'], JSON_UNESCAPED_UNICODE) . PHP_EOL;
//输出
{"code":200,"msg":"请求成功"}
异步请求成功,响应内容:{"code":200,"msg":"success","second":3}
Http::getAsync('http1://easyhttp.yzh52521.cn/api/sleep3.json', function (Response $response) {
echo '异步请求成功,响应内容:' . $response->body() . PHP_EOL;
}, function (RequestException $e) {
echo '异步请求异常,错误信息:' . $e->getMessage() . PHP_EOL;
});
echo json_encode(['code' => 200, 'msg' => '请求成功'], JSON_UNESCAPED_UNICODE) . PHP_EOL;
//输出
{"code":200,"msg":"请求成功"}
异步请求异常错误信息cURL error 1: Protocol "http1" not supported or disabled in libcurl (see https://curl.haxx.se/libcurl/c/libcurl-errors.html)
Http::postAsync(...);
Http::patchAsync(...);
Http::putAsync(...);
Http::deleteAsync(...);
Http::headAsync(...);
Http::optionsAsync(...);
```
#### 异步并发请求
```php
use yzh52521\EasyHttp\Response;
use yzh52521\EasyHttp\RequestException;
$promises = [
Http::getAsync('http://easyhttp.yzh52521.cn/api/sleep3.json'),
Http::getAsync('http1://easyhttp.yzh52521.cn/api/sleep1.json', ['name' => 'yzh52521']),
Http::postAsync('http://easyhttp.yzh52521.cn/api/sleep2.json', ['name' => 'yzh52521']),
];
Http::concurrency(10)->multiAsync($promises, function (Response $response, $index) {
echo "发起第 $index 个异步请求,请求时长:" . $response->json()->second . '秒' . PHP_EOL;
}, function (RequestException $e, $index) {
echo "发起第 $index 个请求失败,失败原因:" . $e->getMessage() . PHP_EOL;
});
//输出
发起第 1 个请求失败失败原因cURL error 1: Protocol "http1" not supported or disabled in libcurl (see https://curl.haxx.se/libcurl/c/libcurl-errors.html)
发起第 2 个异步请求请求时长2
发起第 0 个异步请求请求时长3
```
> 如果未调用concurrency()方法,并发次数默认为$promises的元素个数$promises数组里必须是异步请求
## 使用响应
发起请求后会返回一个 yzh52521\EasyHttp\Response $response的实例该实例提供了以下方法来检查请求的响应
```php
$response->body() : string;
$response->json() : object;
$response->array() : array;
$response->status() : int;
$response->ok() : bool;
$response->successful() : bool;
$response->serverError() : bool;
$response->clientError() : bool;
$response->headers() : array;
$response->header($header) : string;
```
## 异常处理
请求在发生客户端或服务端错误时会抛出 yzh52521\EasyHttp\RequestException $e异常该实例提供了以下方法来返回异常信息
```php
$e->getCode() : int;
$e->getMessage() : string;
$e->getFile() : string;
$e->getLine() : int;
$e->getTrace() : array;
$e->getTraceAsString() : string;
```
## 调试日志
有时候难免要对 Http 的请求和响应包体进行记录以方便查找问题或做什么
```php
//传递一个日志类 thinkphp \think\facade\Log laravel Illuminate\Support\Facades\Log
Http::debug(Log::class)->post(...);
```
## 更新日志
### 2022-05-11
* 新增removeBodyFormat() 用于withOptions 指定body时清除原由的bodyFromat
### 2022-05-10
* 新增发送原生请求的方法client()
* 新增发送原生异步请求的方法clientASync()
### 2021-09-03
* 新增 debug() 调试日志
* 新增 retry() 重试机制
* 修复header重叠的bug
### 2020-03-30
* 修复部分情况下IDE不能智能提示的BUG
* get()、getAsync()方法支持带参数的url
* 新增withUA()方法
* 新增withStream()方法
* 新增asMultipart()方法attach()的别名
* 新增multiAsync()异步并发请求方法
### 2020-03-20
* 新增异步请求getAsync()方法
* 新增异步请求postAsync()方法
* 新增异步请求patchAsync()方法
* 新增异步请求putAsync()方法
* 新增异步请求deleteAsync()方法
* 新增异步请求headAsync()方法
* 新增异步请求optionsAsync()方法
## Todo List
- [x] 异步请求
- [x] 并发请求
- [x] 重试机制
- [ ] 支持http2
- [ ] 支持swoole
# easyhttp