diff --git a/docs/zh_TW/README.md b/docs/zh_TW/README.md index b88e958..4f3c2f9 100644 --- a/docs/zh_TW/README.md +++ b/docs/zh_TW/README.md @@ -37,6 +37,7 @@ echo (string)$response->getBody(); * [ResterClient](rester-client.md) * [ResterCollection](rester-collection.md) +* [Api](api.md) * [Plugins](plugins.md) * [Hooks](hooks.md) * [Asynchronous](asynchronous.md) diff --git a/docs/zh_TW/api.md b/docs/zh_TW/api.md new file mode 100644 index 0000000..5ed5985 --- /dev/null +++ b/docs/zh_TW/api.md @@ -0,0 +1,39 @@ +# Api + +Api 必須住在 Mapping 裡,才能被 [`ResterClient`](rester-client.md) 呼叫到;住在 Mapping 的唯一條件就是要實作 [`ApiInterface`](/src/Api/ApiInterface.php) 。 + +它定義非常簡單,只要實作如何建立 Request 即可 + +```php +public function createRequest( + array $binding = [], + array $queryParams = [], + array $parsedBody = [] +): RequestInterface; +``` + +內建的 [`Path`](/src/Api/Path.php) 與 [`Endpoint`](/src/Api/Endpoint.php) 都有實作這個方法,差別只在 `Path` 只包含 path ,它會需要 Client 的 Base URL ; `Endpoint` 已經是完整的 URL 了。 + +## Customize + +有幾種情況會需要自定義 Api : + +* 同一個 Api 名稱會因為不同的 context 而呼叫 endpoint 有些許不同,如版本 +* `QueryParams` 、 `Header` 等有固定傳入值,如 `QueryParams` 想加入自定義的呼叫來源: `CallBy=MyClient` +* 自定義的包裝格式,如 XML / YAML / 自定義的 JSON 包裝等 + +如果自定義的 Api 需要使用延遲載入的話,則需要實作 Resolver 。 + +## Concept of Resolver + +Resolver 的實作與原理很單純,只要繼承 [`Resolver`](/src/Resolver.php) ,並實作 `resolve` 即可。 `Mapping` 在 `get()` 時,只要發現傳入的值是 array ,即會把第一個值作為 callable ,第二個值做為 parameters 使用 `call_user_func_array()` 執行。 + +```php +// $api is Array +$callable = $api[0]; +$parameters = $api[1]; + +$apiInstance = call_user_func_array($callable, $parameters); +``` + +也因此 Resolve 不會把 `resolve` 定義成抽象,因為 Api 可以自定義, parameter 就有可能不是固定的,並且它還可以透過 PHP 7 的型別檢查來確保傳入值是正確的。 diff --git a/docs/zh_TW/rester-client.md b/docs/zh_TW/rester-client.md index b70142b..12ef24b 100644 --- a/docs/zh_TW/rester-client.md +++ b/docs/zh_TW/rester-client.md @@ -83,3 +83,26 @@ $resterClient->foo(); // POST https://www.some-url.com/bar $resterClient->bar(); ``` + +## Lazy Loading + +Mapping 實作了延遲載入。實際範例如下: + +```php +$pathResolver = new PathResolver(); +$endpointResolver = new EndpointResolver(); + +$resterClient = new ResterClient('http://127.0.0.1'); +$resterClient->provisionMapping([ + 'getFoo' => [$pathResolver, ['GET', '/foo']], + 'postFoo' => [$pathResolver, ['POST', '/foo']], + 'putFoo' => [$pathResolver, ['PUT', '/foo']], + 'deleteFoo' => [$pathResolver, ['DELETE', '/foo']], + 'getBar' => [$endpointResolver, ['GET', 'https://www.some-url.com/bar'], + 'postBar' => [$endpointResolver, ['POST', 'https://www.some-url.com/bar'], + 'putBar' => [$endpointResolver, ['PUT', 'https://www.some-url.com/bar'], + 'deleteBar' => [$endpointResolver, ['DELETE', 'https://www.some-url.com/bar'], +]); +``` + +延遲載入的細節可以參考 [Api](api.md) 文件。