[stream]怎麼從程式內部 call api?

通常撰寫完成 api 後，我會使用 POSTMAN 測試這支 api 功能是否正常運行。啊~如果現在要從程式內部， call 其他 api 拿資料，該怎麼做呢?!

• 根據我得爬文後，有四種作法，諸如 串流(strem), curl, Guzzle (PHP Packagist), SDK
• 本文介紹 串流(strem)

串流 (strem)

PHP funtion get_file_contents() ，從字面上來看，會覺得這個 function 只能拿到 file 內容，殊不知，file_get_contents 可以拿到 URL 的內容！! (URL 包括 HTTP 和 FTP URLs)

至於為什麼 get_file_contents() 可以取得 URL 上的資料，就要從 PHP 的 Runtime Configuration 著手。或許你不知道 PHP Runtime Configuration 是什麼，但是猶記得安裝 PHP 時，有一個經典畫面，一定瞧過！

將頁面拉到 Core 的部分，端看 allow_url_fopen 的 default 設定是 On，在 remote files 提到 allow_url_fopen 可以使用包含 HTTP URL 和 FTP URL 作為大多數 function 的参數
也就是說，file_get_contents() 的參數可以使用 URL 來進行各項操作，而不僅僅是訪問本地文件

<?php
$rand = file_get_contents("https://jsonplaceholder.typicode.com/posts/1");

var_dump($rand);

/* (string)
 * {
 *   "userId": 1,  
 *   "id": 1,
 *   "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
 *   "body": "quia et suscipit\nsuscipit recusa..."
 * }
 */ 

file_get_contents()

Stream function 是 PHP 的一部分，使用 stream function 無須安裝，stream 是通用化文件、網絡、數據壓縮和其他共享一組通用功能和用途的操作的方式。PHP 提供了蠻多的 stream 封裝協議 如圖:

PHP 提供多個 context options and parameters 用於 『文件系統』和『串流封裝 (stream wrappers)』，建立 context 方法為 stream_context_create()，PHP 提供 HTTP context option，本文用到的 Http option 諸如: method, header, content 等。

file_get_contents() 只能 GET 嗎?

示範 file_get_contents() 使用 PATCH，操作如下:

<?php
// 資料中的基本信息 轉為 json 格式, 自定義 key & value
$payload = json_encode(
  [
    "title" => "Round world",
    "body"  => "whatever yu want",
    "game"  => "5X Ruby",
  ]
);

// $options 格式參考 PHP 文件 `HTTP context options`
$options = [
  "http" => [
    "method"   => "PATCH",
    "header"   => "Content-type: application/json; Charset=UTF-8",
    // 添加的內容($payload) 放在 content
    "content"  => $payload
  ]
];

// 依據 $options 建立 stream(串流) 的內容
$context = stream_context_create($options);

// URL 經 stream(串流) 後的內容
$rand = file_get_contents("https://jsonplaceholder.typicode.com/posts/1", false, $context);

var_dump($rand);

/*
 * {
 *   "userId": 1,  
 *   "id": 1,
 *   "title": "Round world",
 *   "body": "whatever yu want",
 *   "game": "5X Ruby"
 * }
 */ 

p.s 因 URL 是 Jsonplaceholder，這範例是模擬 透過 stream 更新 (PATCH) URL 內容，遂這不是真正的更新資源，只是 '模擬' 更新的效果

file_get_contents() 後，我怎麼知道 http 狀態碼?

拿到資料 等於 200 Ok; 拿不到資料 等於 404 Not Found
經 file_get_contents() 後，使用 PHP 內建變數 $http_response_header 取得 header 內容

<?php

// 前情設定略
// 設定錯誤的 URL: "https://jsonplaceholder.typicode.com/postsXXX"
$rand = file_get_contents("https://jsonplaceholder.typicode.com/postsXXX", false, $context);

// 取得 header 內容
var_dump($http_response_header);

冷知識補充

補充文章提到的名詞解釋:

• 本文所用的 URL 取至 Jsonplaceholder — Jsonplaceholder is free fake API for testing and prototyping.
• fopen() — Opens file or URL
• payload — Server 發送或接收的資料中的基本信息
• 若 allow_url_fopen 是 Off，可以從 php.ini 變更設定

結語

file_get_contents() 可以用 URL 當參數，也可以搭配 stream 做到 POST, PUT..等效果，當然，PHP 也提供 $http_response_header 供使用者 header 資訊，而這些功能都是 PHP 內建，無須在額外裝載其他套件。下階段要介紹怎麼使用 curl

參考文章

1 How to call APIs from PHP: file_get_contents, cURL, Guzzle and SDKs
2 file_get_contents()
3 Runtime Configuration
4 Remote files
5 Introduction stream
6 stream 封裝協議
7 Context options and parameters
8 HTTP context option
9 $http_response_header
10 Jsonplaceholder
11 payload