Skip to content

Commit

Permalink
Update zh and en doc.
Browse files Browse the repository at this point in the history
  • Loading branch information
@twose
twose committed Apr 5, 2018
1 parent 5b04239 commit 1ee2470
Show file tree
Hide file tree
Showing 2 changed files with 120 additions and 51 deletions.
150 changes: 107 additions & 43 deletions README-en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

[![Latest Version](https://img.shields.io/github/release/swlib/swlib.svg?style=flat-square)](https://github.com/swlib/saber/releases)
[![Build Status](https://travis-ci.org/swlib/saber.svg?branch=master)](https://github.com/swlib/saber/releases)
[![Php Version](https://img.shields.io/badge/php-%3E=7.0-brightgreen.svg?maxAge=2592000)](https://secure.php.net/)
[![Php Version](https://img.shields.io/badge/php-%3E=7.1-brightgreen.svg?maxAge=2592000)](https://secure.php.net/)
[![Swoole Version](https://img.shields.io/badge/swoole-%3E=2.1.2-brightgreen.svg?maxAge=2592000)](https://github.com/swoole/swoole-src)
[![Saber License](https://img.shields.io/hexpm/l/plug.svg?maxAge=2592000)](https://github.com/swlib/saber/blob/master/LICENSE)

## 简介
## Intro

The PHP high-performance HTTP client for `Swoole Humanized Component Library`, based on Swoole native coroutine client, supports multiple styles of operation, provides high-performance solutions at the bottom, allows developers to focus on feature development, and emancipate from traditional synchronous blocking network libs.

Expand Down Expand Up @@ -38,74 +38,93 @@ The PHP high-performance HTTP client for `Swoole Humanized Component Library`, b

All of Saber's static methods have a corresponding method in the instance. The static method is implemented by a default client instance.

### Easy Request
### Coroutine

Swoole implements coroutine scheduling at the bottom layer, and the business layer does not need to be aware of it. It needs to be used in event callback functions such as `onRequet`, `onReceive`, and `onConnect`, or wrapped using the go keyword (`swoole.use_shortname` is enabled by default).

```php
go(function () {
Saber::get('http://httpbin.org/get');
Saber::post('http://httpbin.org/post');
Saber::put('http://httpbin.org/put');
Saber::patch('http://httpbin.org/patch');
Saber::delete('http://httpbin.org/delete');
});
echo Saber::get('http://httpbin.org/get');
})
```

### Easy Request

```php
Saber::get('http://httpbin.org/get');
Saber::post('http://httpbin.org/post');
Saber::put('http://httpbin.org/put');
Saber::patch('http://httpbin.org/patch');
Saber::delete('http://httpbin.org/delete');
```

### Create Instance

API proxy service applicable

```php
go(function () {
$saber = Saber::create([
'base_uri' => 'http://httpbin.org',
'headers' => ['Accept-Language' => 'en,zh-CN;q=0.9,zh;q=0.8']
]);
$response = $saber->get('/get');
echo $response;
});
$saber = Saber::create([
'base_uri' => 'http://httpbin.org',
'headers' => [
'User-Agent' => null,
'Accept-Language' => 'en,zh-CN;q=0.9,zh;q=0.8',
'DNT' => '1'
],
]);
echo $saber->get('/get');
echo $saber->post('/post');
echo $saber->patch('/patch');
echo $saber->put('/put');
echo $saber->delete('/delete');
```

### Multi Request
Note: A concurrent redirection optimization scheme is used here. Multiple redirects are always concurrent and do not degenerate into a single request for the queue.
```php
go(function () {
$responses = Saber::requests([
['uri' => 'http://github.com/'],
['uri' => 'http://github.com/'],
['uri' => 'https://github.com/']
]);
echo "multi-requests [ {$responses->success_num} ok, {$responses->error_num} error ]:\n" .
"consuming-time: {$responses->time}s\n";
});
$responses = Saber::requests([
['uri' => 'http://github.com/'],
['uri' => 'http://github.com/'],
['uri' => 'https://github.com/']
]);
echo "multi-requests [ {$responses->success_num} ok, {$responses->error_num} error ]:\n" ."consuming-time: {$responses->time}s\n";

// multi-requests [ 3 ok, 0 error ]:
// consuming-time: 0.79090881347656s
```
```php
// Arguments alias make it easier.
$saber = Saber::create(['base_uri' => 'http://httpbin.org']);
echo $saber->requests([
['get','/get'],
['post','/post'],
['patch','/patch'],
['put','/put'],
['delete','/delete']
]);
```

### HTTP Proxy

Support HTTP and Socks5

```php
go(function () {
$uri = 'http://myip.ipip.net/';
echo Saber::get($uri, ['proxy' => 'http://127.0.0.1:1087'])->body;
echo Saber::get($uri, ['proxy' => 'socks5://127.0.0.1:1086'])->body;
});
$uri = 'http://myip.ipip.net/';
echo Saber::get($uri, ['proxy' => 'http://127.0.0.1:1087'])->body;
echo Saber::get($uri, ['proxy' => 'socks5://127.0.0.1:1086'])->body;
```

### PSR Style

```php
go(function () {
$response = Saber::psr()
->withMethod('POST')
->withUri(new Uri('http://httpbin.org/post?foo=bar'))
->withQueryParams(['foo' => 'option is higher-level than uri'])
->withHeader('content-type', ContentType::JSON)
->withBody(new BufferStream(json_encode(['foo' => 'bar'])))
->exec()->recv();

echo $response->getBody();
});
$response = Saber::psr()
->withMethod('POST')
->withUri(new Uri('http://httpbin.org/post?foo=bar'))
->withQueryParams(['foo' => 'option is higher-level than uri'])
->withHeader('content-type', ContentType::JSON)
->withBody(new BufferStream(json_encode(['foo' => 'bar'])))
->exec()->recv();

echo $response->getBody();
```


Expand Down Expand Up @@ -139,4 +158,49 @@ You can then later update Saber using composer:

```
composer update
```
```



## Configuration parameter table

`|` splitting multiple selectable values

| key | type | introduction | example | remark |
| --------------------- | --------------------- | ------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| protocol_version | string | | 1.1 | HTTP2 in the roadmap |
| base_uri | string | | `http://httpbin.org` | Will merge with uri according to rfc3986 |
| uri | string | | `http://httpbin.org/get` \| `/get` \| `get` | U can use absolute and relative paths |
| method | string | | `get` \| `post` \| `head` \| `patch` \| `put` \| `delete` | The underlying layer is automatically converted to uppercase |
| headers | array | | `['DNT' => '1']` \| `['accept' => ['text/html'], ['application/xml']]` | The field names are case-insensitive, but the original case rules at the time of setting are retained. Each underlying field value is automatically split into arrays according to PSR-7. |
| cookies | `array`\|`string` | | `['foo '=> 'bar']` \| `'foo=bar; foz=baz'` | The underlying is automatically converted to a Cookies object and its domain is set to the current uri, with browser-level complete properties. |
| useragent | string | | | The default is macos platform chrome |
| redirect | int | max-value | 5 | The default is 3, 0 is not redirected. |
| keep_alive | bool | | `true` \| `false` | The default is true, the connection will be reused automatically when redirecting |
| content_type | string | | `text/plain` \| `Swlib\Http\ContentType::JSON` | default is `application/x-www-form-urlencoded` |
| data | `array` \| `string` | | `'foo=bar&dog=cat'` \|` ['foo' => 'bar']` | Will automatically encode data based on content_type |
| before | `callable` \| `array` | interceptor before request | `function(Request $request){}` | Specific reference to the interceptor section |
| after | `callable` \| `array` | interceptor after response | `function(Response $response){}` | Ditto. |
| timeout | float | | 0.5 | Default 5s, support millisecond timeout |
| proxy | string | | `http://127.0.0.1:1087` \| `socks5://127.0.0.1:1087` | suport `http` and `socks5` |
| ssl | int | enable ssl? | `0=disable` `1=enable` `2=auto` | auto default |
| cafile | string | ca file | `__DIR__ . '/cacert.pem'` | |
| ssl_verify_peer | bool | Verify server certificate | `false` \| `true` | close default |
| ssl_allow_self_signed | bool | Allow self-signed certificates | `true` \| `false` | allow default |


### Alias

| key | alias |
| ------------ | ------------- |
| method | 0 |
| uri | `1` \| `url` |
| data | `2` \| `body` |
| base_uri | base_url |
| after | callback |
| content_type | content-type |
| cookies | cookie |
| headers | header |
| redirect | follow |
| form_data | query |
| useragent | ua |
21 changes: 13 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ $responses = Saber::requests([
['uri' => 'http://github.com/'],
['uri' => 'https://github.com/']
]);
echo "multi-requests [ {$responses->success_num} ok, {$responses->error_num} error ]:\n" ."consuming-time: {$responses->time}s\n";
echo "multi-requests [ {$responses->success_num} ok, {$responses->error_num} error ]:\n" ."consuming-time: {$responses->time}s\n";

// multi-requests [ 3 ok, 0 error ]:
// consuming-time: 0.79090881347656s
Expand Down Expand Up @@ -183,7 +183,7 @@ composer update
| after | `callable` \| `array` | 响应后拦截器 | `function(Response $response){}` | 具体参考拦截器一节 |
| timeout | float | 超时时间 | 0.5 | 默认5s, 支持毫秒级超时 |
| proxy | string | 代理 | `http://127.0.0.1:1087` \| `socks5://127.0.0.1:1087` | 支持http和socks5 |
| ssl | int | 是否开启ssl连接 | `0=关闭` | `1=开启` | `2=自动` | 默认值为自动, 遇到https连接时底层会自动开启 |
| ssl | int | 是否开启ssl连接 | `0=关闭` `1=开启` `2=自动` | 默认自动 |
| cafile | string | ca文件 | `__DIR__ . '/cacert.pem'` | 默认自带 |
| ssl_verify_peer | bool | 验证服务器端证书 | `false` \| `true` | 默认关闭 |
| ssl_allow_self_signed | bool | 允许自签名证书 | `true` \| `false` | 默认允许 |
Expand All @@ -194,9 +194,14 @@ composer update

| key | alias |
| -------- | ----------- |
| method | `0` |
| uri | `1` |
| data | `2` |
| base_uri | base_url |
| after | callback |

|method|0|
|uri|`1` \| `url`|
|data|`2` \| `body`|
|base_uri|base_url|
|after|callback|
|content_type|content-type|
|cookies|cookie|
|headers|header|
|redirect|follow|
|form_data|query|
|useragent|ua|

0 comments on commit 1ee2470

Please sign in to comment.