【PHP類庫】Requests - A humble HTTP request library

Requests是一個PHP的HTTP類庫。相對於cURL等類庫來講，它具備簡單易用且友好的API，且不依賴於cURL。它支持HEAD、 GET、 POST、 PUT、 DELETE和PATCH等方法，基本能知足任何形式的HTTP請求。

Requests不依賴於任何PHP標準庫外的擴展，惟一的要求就是須要PHP5.2+的版本。可是若是PHP的cURL可用，Requests會優先使用它，不然會使用socket。

安裝和使用

經過Composer安裝

{
    "require": {
        "rmccue/requests": ">=1.0"
    },
    "autoload": {
        "psr-0": {"Requests": "library/"}
    }
}

自動加載

可使用Composer的加載器：

phpinclude('/path/to/composer/vendor/autoload.php');

也可使用Requests自帶的：

phpinclude('/path/to/library/Requests.php');

Requests::register_autoloader();

各類請求

GET請求

php$response = Requests::get('http://httpbin.org/get');

POST請求

php$response = Requests::post('http://httpbin.org/post');

須要傳數據的話，可使用第三個參數：

php$data = array('key1' => 'value1', 'key2' => 'value2');
$response = Requests::post('http://httpbin.org/post', array(), $data);

若是須要傳原始數據的話，第三個參數請傳字符串。

其餘請求

其餘請求方法都大同小異：

php$response = Requests::put('http://httpbin.org/put');

$response = Requests::delete('http://httpbin.org/delete');

$response = Requests::patch('http://httpbin.org/patch', array('If-Match' => 'e0023aa4e'));

$response = Requests::head('http://httpbin.org/headers');

須要注意的是equests::patch()方法的第二個參數爲必傳。

Requests::request()方法

看API文檔，你會發現這些方法接受的參數幾乎同樣：$url，$headers，$data（只有POST、PUT和PATCH有），$options。事實上它們只是對Requests::request()方法進行了一次封裝：

php/**
 * Send a GET request
 */
public static function get($url, $headers = array(), $options = array()) {
    return self::request($url, $headers, null, self::GET, $options);
}

/**
 * Send a HEAD request
 */
public static function head($url, $headers = array(), $options = array()) {
    return self::request($url, $headers, null, self::HEAD, $options);
}

/**
 * Send a DELETE request
 */
public static function delete($url, $headers = array(), $options = array()) {
    return self::request($url, $headers, null, self::DELETE, $options);
}

/**
 * Send a POST request
 */
public static function post($url, $headers = array(), $data = array(), $options = array()) {
    return self::request($url, $headers, $data, self::POST, $options);
}

/**
 * Send a PUT request
 */
public static function put($url, $headers = array(), $data = array(), $options = array()) {
    return self::request($url, $headers, $data, self::PUT, $options);
}

$header容許咱們自定義請求頭，例如POST方法的話，咱們一般須要指定Content-Type，使服務器知道咱們正在發送的的數據是什麼格式：

php$url = 'https://api.github.com/some/endpoint';
$headers = array('Content-Type' => 'application/json');
$data = array('some' => 'data');
$response = Requests::post($url, $headers, json_encode($data));

$options容許咱們對請求進行配置，例如超時時間：

php$options = array(
    'timeout' => 5
);
$response = Requests::get('https://httpbin.org/', array(), $options);

更多的選項配置請看：http://requests.ryanmccue.info/api/source-class-Requests.html#_request

Requests裏全部的請求方法（HEAD、 GET、 POST、 PUT、 DELETE和PATCH）返回的都是一個Requests_Response對象，這個對象包含了響應的各類信息：

• $body：響應體。
• $raw：原始的HTTP響應數據。
• $headers：響應頭。
• $status_code：狀態碼。
• $success：標識請求是否成功。
• $redirects：請求的重定向次數。
• $url：請求的URL。
• $history：請求的歷史記錄。
• $cookies：cookie信息。

更多Requests_Response的信息請看：http://requests.ryanmccue.info/api/source-class-Requests.html#_request

Session處理

當你須要對同一網站發出多個請求，那麼Requests_Session對象能夠幫到輕易的設置一些默認參數：

php$url = 'https://api.github.com/';
$header = array('X-ContactAuthor' => 'rmccue');
$data = array();
$options = array('useragent' => 'My-Awesome-App');
$session = new Requests_Session($url, $header, $data, $options);

$response = $session->get('/zen');

Requests_Session的構造函數接受url、headers、data和options這4個參數，順序跟Requests::request()方法一致。同時你也能夠經過訪問屬性的方式去修改options參數：

php// 設置option屬性
$session->useragent = 'My-Awesome-App';

// 跟上面的做用一致
$session->options['useragent'] = 'My-Awesome-App';

更多Requests_Session的信息請看：http://requests.ryanmccue.info/api/source-class-Requests_Session.html

HTTPS請求

Requests會默認幫忙處理HTTPS請求，就跟在瀏覽器訪問HTTPS網站同樣：

php$response = Requests::get('https://httpbin.org/');

可是若是你想使用其餘的證書或者自簽證書，你能夠指定證書文件（PEM格式）：

php$options = array(
    'verify' => '/path/to/cacert.pem'
);
$response = Requests::get('https://httpbin.org/', array(), $options);

若是你想禁用HTTPS的驗證，能夠經過設置options：'verify' => false。

HTTP基本驗證

HTTP基本驗證功能能夠經過options的auth實現：

php$options = array(
    'auth' => array('user', 'password')
);
Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options);

進階使用

使用代理

代理能夠經過options的proxy實現：

php$options = array(
    'proxy' => '127.0.0.1:3128'
);
Requests::get('http://httpbin.org/ip', array(), $options);

若是代理須要驗證：

php$options = array(
    'proxy' => array( '127.0.0.1:3128', 'my_username', 'my_password' )
);
Requests::get('http://httpbin.org/ip', array(), $options);

鉤子

經過Requests的鉤子系統，咱們能夠經過註冊本身的鉤子去擴展Requests的功能：

php$hooks = new Requests_Hooks();
$hooks->register('requests.after_request', 'mycallback');

$request = Requests::get('http://httpbin.org/get', array(), array('hooks' => $hooks));

Request提供的鉤子請看：http://requests.ryanmccue.info/docs/hooks.html

自定義驗證

經過實現Requests_Auth接口，咱們能夠爲請求添加自定義的驗證。假設服務器會檢查HTTP請求裏的Hotdog請求頭的值是否是爲Yummy。咱們先實現咱們的驗證類：

phpclass MySoftware_Auth_Hotdog implements Requests_Auth {
    protected $password;

    public function __construct($password) {
        $this->password = $password;
    }

    public function register(Requests_Hooks &$hooks) {
        $hooks->register('requests.before_request', array(&$this, 'before_request'));
    }

    public function before_request(&$url, &$headers, &$data, &$type, &$options) {
        $headers['Hotdog'] = $this->password;
    }
}

能夠看到，類實現了Requests_Auth接口，同時代碼實現也用到了鉤子。下面咱們經過options的auth去調用咱們的自定義驗證：

php$options = array(
    'auth' => new MySoftware_Auth_Hotdog('yummy')
);
$response = Requests::get('http://hotdogbin.org/admin', array(), $options);

Why Requests？

文章開始提到了Requests的一些優勢，這個官網有個專門的頁面進行詳細的介紹，同時還提到了Requests跟其餘相似類庫的對比。經過這個對比，你們對Requests會有進一步的認識，同時也科普下還有哪些HTTP請求相關的類庫。
請猛擊：http://requests.ryanmccue.info/docs/why-requests.html

參考

http://requests.ryanmccue.info/