Browse Source

add docs, fix user agent

* added docs for how to use the library
* fixed setting the user agent for requests
* add option to send http headers for HEAD requests
pull/1/head 0.1.1
Aaron Parecki 4 years ago
parent
commit
7409b0a44f
No known key found for this signature in database GPG Key ID: 276C2817346D6056
8 changed files with 198 additions and 9 deletions
  1. +1
    -0
      CONTRIBUTING.md
  2. +162
    -1
      README.md
  3. +12
    -0
      example.php
  4. +15
    -2
      src/p3k/HTTP.php
  5. +3
    -1
      src/p3k/HTTP/Curl.php
  6. +2
    -2
      src/p3k/HTTP/Stream.php
  7. +1
    -1
      src/p3k/HTTP/Test.php
  8. +2
    -2
      src/p3k/HTTP/Transport.php

+ 1
- 0
CONTRIBUTING.md View File

@ -0,0 +1 @@
By submitting code to this project, you agree to irrevocably release it under the same license as this project. See README.md for more details.

+ 162
- 1
README.md View File

@ -1,4 +1,165 @@
# p3k-http
A simple wrapper around the PHP curl functions, used by https://p3k.io projects.
A simple HTTP client, used by https://p3k.io projects.
## Usage
### GET
```php
$http = new p3k\HTTP();
$headers = [
'Accept: text/html, */*'
];
$response = $http->get('http://example.com/', $headers);
```
### POST
```php
$http = new p3k\HTTP();
$headers = [
'Accept: application/json',
'Content-type: application/json'
];
$response = $http->post('http://example.com/', json_encode([
'foo' => 'bar'
], $headers);
```
### HEAD
```php
$http = new p3k\HTTP();
$headers = [
'Accept: text/html, */*'
];
$response = $http->head('http://example.com/', $headers);
```
### Response
The get/post/head functions will return an array with the following properties:
* `code` - integer, the HTTP response code that was returned
* `headers` - array, the HTTP headers returned
* `rels` - array, the parsed HTTP rel values from any `Link` headers
* `body` - string, the body of the HTTP response, or false/omit for a HEAD request
* `error` - string, an error string. see below for the enumerated list.
* `error_description` - string,
* `url` - string, the final URL retrieved after following any redirects
* `debug` - string, the full HTTP response
#### `headers`
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.
```
[headers] => Array
(
[Server] => nginx/1.12.0
[Content-Type] => text/html; charset=UTF-8
[Transfer-Encoding] => chunked
[Connection] => keep-alive
[Cache-Control] => no-cache
[Link] => Array
(
[0] => <https://switchboard.p3k.io/>; rel="hub"
[1] => <https://aaronparecki.com/auth>; rel="authorization_endpoint"
[2] => <https://aaronparecki.com/micropub>; rel="micropub"
[3] => <https://aaronparecki.com/auth/token>; rel="token_endpoint"
[4] => <https://aaronparecki.com/>; rel="self"
)
[Date] => Fri, 28 Apr 2017 18:40:42 GMT
[Strict-Transport-Security] => max-age=2592000
[X-No-Cache] => 0
[X-Cache] => EXPIRED
)
```
#### `rels`
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.
```
[rels] => Array
(
[hub] => Array
(
[0] => https://switchboard.p3k.io/
)
[authorization_endpoint] => Array
(
[0] => https://aaronparecki.com/auth
)
[micropub] => Array
(
[0] => https://aaronparecki.com/micropub
)
[token_endpoint] => Array
(
[0] => https://aaronparecki.com/auth/token
)
[self] => Array
(
[0] => https://aaronparecki.com/
)
)
```
### Options
There are a few options you can set when making HTTP requests, to configure how the request will behave.
* `$http->set_user_agent('String')` - A shortcut for setting the user agent header.
* `$http->set_max_redirects(2)` - The maximum number of redirects to follow. Defaults to 8.
* `$http->set_timeout(10)` - The timeout in seconds for waiting for a response. Defaults to 4.
#### User Agent
You can set the user agent when you first instantiate the HTTP object:
```php
$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');
$http->get('http://example.com/');
```
Alternately, you can change it before each request:
```php
$http = new p3k\HTTP();
$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');
$http->get('http://example.com/');
```
## Transports
By default, the library will use the PHP curl functions to make the HTTP request.
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.
Define a new class that implements the `p3k\HTTP\Transport` interface. That interface documents the return values expected as well.
Then you can set the transport after you create the main HTTP object.
```php
$http = new p3k\HTTP();
$http->set_transport(new p3k\HTTP\Stream()); // or your custom class here
```
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.
## License
Copyright 2017 by Aaron Parecki
Available under the MIT license.

+ 12
- 0
example.php View File

@ -0,0 +1,12 @@
<?php
require('vendor/autoload.php');
$http = new p3k\HTTP();
$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');
$headers = [
'Accept: text/html'
];
$response = $http->get('http://aaronpk.com', $headers);
print_r($response['headers']);

+ 15
- 2
src/p3k/HTTP.php View File

@ -20,6 +20,10 @@ class HTTP {
}
}
public function set_user_agent($ua) {
$this->_user_agent = $ua;
}
public function set_max_redirects($max) {
$this->_max_redirects = $max;
}
@ -35,6 +39,9 @@ class HTTP {
public function get($url, $headers=[]) {
$this->_transport->set_timeout($this->_timeout);
$this->_transport->set_max_redirects($this->_max_redirects);
if($this->_user_agent) {
$headers[] = 'User-Agent: ' . $this->_user_agent;
}
$response = $this->_transport->get($url, $headers);
$response = $this->_build_response($response);
return $response;
@ -43,15 +50,21 @@ class HTTP {
public function post($url, $body, $headers=[]) {
$this->_transport->set_timeout($this->_timeout);
$this->_transport->set_max_redirects($this->_max_redirects);
if($this->_user_agent) {
$headers[] = 'User-Agent: ' . $this->_user_agent;
}
$response = $this->_transport->post($url, $body, $headers);
$response = $this->_build_response($response);
return $response;
}
public function head($url) {
public function head($url, $headers=[]) {
$this->_transport->set_timeout($this->_timeout);
$this->_transport->set_max_redirects($this->_max_redirects);
$response = $this->_transport->head($url);
if($this->_user_agent) {
$headers[] = 'User-Agent: ' . $this->_user_agent;
}
$response = $this->_transport->head($url, $headers);
$response = $this->_build_response($response);
return $response;
}

+ 3
- 1
src/p3k/HTTP/Curl.php View File

@ -54,9 +54,11 @@ class Curl implements Transport {
);
}
public function head($url) {
public function head($url, $headers=[]) {
$ch = curl_init($url);
$this->_set_curlopts($ch, $url);
if($headers)
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_NOBODY, true);
$response = curl_exec($ch);
return array(

+ 2
- 2
src/p3k/HTTP/Stream.php View File

@ -34,9 +34,9 @@ class Stream implements Transport {
return $this->_fetch($url, $context);
}
public function head($url) {
public function head($url, $headers=[]) {
set_error_handler("p3k\HTTPStream::exception_error_handler");
$context = $this->_stream_context('HEAD', $url);
$context = $this->_stream_context('HEAD', $url, false, $headers);
return $this->_fetch($url, $context);
}

+ 1
- 1
src/p3k/HTTP/Test.php View File

@ -41,7 +41,7 @@ class Test implements Transport {
return $this->_read_file($url);
}
public function head($url) {
public function head($url, $headers=[]) {
$response = $this->_read_file($url);
return array(
'code' => $response['code'],

+ 2
- 2
src/p3k/HTTP/Transport.php View File

@ -24,9 +24,9 @@ interface Transport {
* unknown
*/
public function get($url, $headers);
public function get($url, $headers=[]);
public function post($url, $body, $headers=[]);
public function head($url);
public function head($url, $headers=[]);
public function set_timeout($timeout);
public function set_max_redirects($max_redirects);

Loading…
Cancel
Save