You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

191 lines
5.9 KiB

8 years ago
  1. # p3k-http
  2. A simple HTTP client, used by https://p3k.io projects.
  3. ## Usage
  4. ### GET
  5. ```php
  6. $http = new p3k\HTTP();
  7. $headers = [
  8. 'Accept: text/html, */*'
  9. ];
  10. $response = $http->get('http://example.com/', $headers);
  11. ```
  12. ### POST
  13. ```php
  14. $http = new p3k\HTTP();
  15. $headers = [
  16. 'Accept: application/json',
  17. 'Content-type: application/json'
  18. ];
  19. $response = $http->post('http://example.com/', json_encode([
  20. 'foo' => 'bar'
  21. ], $headers);
  22. ```
  23. ### HEAD
  24. ```php
  25. $http = new p3k\HTTP();
  26. $headers = [
  27. 'Accept: text/html, */*'
  28. ];
  29. $response = $http->head('http://example.com/', $headers);
  30. ```
  31. ### Response
  32. The get/post/head functions will return an array with the following properties:
  33. * `code` - integer, the HTTP response code that was returned
  34. * `headers` - array, the HTTP headers returned
  35. * `rels` - array, the parsed HTTP rel values from any `Link` headers
  36. * `body` - string, the body of the HTTP response, or false/omit for a HEAD request
  37. * `redirects` - array, the redirects followed, or omitted when not supported
  38. * `error` - string, an error string. see below for the enumerated list.
  39. * `error_description` - string,
  40. * `url` - string, the final URL retrieved after following any redirects
  41. * `debug` - string, the full HTTP response
  42. #### `headers`
  43. The `headers` key will be an array of all the header values returned. The values will be either a string or array depending on whether there were multiple values returned for a given header name.
  44. ```
  45. [headers] => Array
  46. (
  47. [Server] => nginx/1.12.0
  48. [Content-Type] => text/html; charset=UTF-8
  49. [Transfer-Encoding] => chunked
  50. [Connection] => keep-alive
  51. [Cache-Control] => no-cache
  52. [Link] => Array
  53. (
  54. [0] => <https://switchboard.p3k.io/>; rel="hub"
  55. [1] => <https://aaronparecki.com/auth>; rel="authorization_endpoint"
  56. [2] => <https://aaronparecki.com/micropub>; rel="micropub"
  57. [3] => <https://aaronparecki.com/auth/token>; rel="token_endpoint"
  58. [4] => <https://aaronparecki.com/>; rel="self"
  59. )
  60. [Date] => Fri, 28 Apr 2017 18:40:42 GMT
  61. [Strict-Transport-Security] => max-age=2592000
  62. [X-No-Cache] => 0
  63. [X-Cache] => EXPIRED
  64. )
  65. ```
  66. #### `rels`
  67. The `rels` key will be the parsed version of any HTTP `Link` headers that contain a rel value. All values will be arrays even if there is only one value.
  68. ```
  69. [rels] => Array
  70. (
  71. [hub] => Array
  72. (
  73. [0] => https://switchboard.p3k.io/
  74. )
  75. [authorization_endpoint] => Array
  76. (
  77. [0] => https://aaronparecki.com/auth
  78. )
  79. [micropub] => Array
  80. (
  81. [0] => https://aaronparecki.com/micropub
  82. )
  83. [token_endpoint] => Array
  84. (
  85. [0] => https://aaronparecki.com/auth/token
  86. )
  87. [self] => Array
  88. (
  89. [0] => https://aaronparecki.com/
  90. )
  91. )
  92. ```
  93. #### `redirects`
  94. The `redirects` key will be an array of all the redirects followed to retrieve the final response. This key may be omitted if the transport does not support retrieving the data.
  95. ```php
  96. Array
  97. (
  98. [0] => Array
  99. (
  100. [code] => 301
  101. [from] => http://aaronpk.com/
  102. [to] => https://aaronpk.com/
  103. )
  104. [1] => Array
  105. (
  106. [code] => 301
  107. [from] => https://aaronpk.com/
  108. [to] => https://aaronparecki.com/
  109. )
  110. )
  111. ```
  112. The `code` key within a redirect array is the HTTP status code that came with it. This can be used for separating permanent redirects (301) from temporary ones (302).
  113. ### Options
  114. There are a few options you can set when making HTTP requests, to configure how the request will behave.
  115. * `$http->set_user_agent('String')` - A shortcut for setting the user agent header.
  116. * `$http->set_max_redirects(2)` - The maximum number of redirects to follow. Defaults to 8.
  117. * `$http->set_timeout(10)` - The timeout in seconds for waiting for a response. Defaults to 4.
  118. #### User Agent
  119. You can set the user agent when you first instantiate the HTTP object:
  120. ```php
  121. $http = new p3k\HTTP('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36 p3k-http/0.1.0');
  122. $http->get('http://example.com/');
  123. ```
  124. Alternately, you can change it before each request:
  125. ```php
  126. $http = new p3k\HTTP();
  127. $http->set_user_agent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36 p3k-http/0.1.0');
  128. $http->get('http://example.com/');
  129. ```
  130. ## Transports
  131. By default, the library will use the PHP curl functions to make the HTTP request.
  132. You can optionally define your own transport to use to make HTTP requests instead. This allows you to use an existing HTTP request mechanism you may have rather than using curl or the PHP stream functions.
  133. Define a new class that implements the `p3k\HTTP\Transport` interface. That interface documents the return values expected as well.
  134. Then you can set the transport after you create the main HTTP object.
  135. ```php
  136. $http = new p3k\HTTP();
  137. $http->set_transport(new p3k\HTTP\Stream()); // or your custom class here
  138. ```
  139. The library ships with two alternative transport mechanisms, `p3k\HTTP\Stream` and `p3k\HTTP\Test`. The Stream transport uses `file_get_contents` with all the necessary config options to make it work. This is useful when running in Google App Engine. The Test transport will read HTTP responses from files, so that you can write tests that simulate making HTTP calls. See https://github.com/aaronpk/XRay/tree/master/tests for an example of using this transport.
  140. ## License
  141. Copyright 2017 by Aaron Parecki
  142. Available under the MIT license.