Permalink
Browse files

Add proposal for HTTP Client

  • Loading branch information...
1 parent b475eba commit 829ecc1e2498883bbb73e7183fcb9728a3051049 @beberlei committed Mar 24, 2012
Showing with 99 additions and 0 deletions.
  1. +99 −0 proposed/http-client.md
View
@@ -0,0 +1,99 @@
+## Introduction
+
+Many libraries and applications require an HTTP client to talk to other servers. In general all these libraries either ship their own HTTP client library, or use low-level PHP functionality such as `file_get_contents`, ext/curl or the ext/socket. Depending on the use-cases there are very tricky implementation details to be handled such as proxies, SSL, authentication protocols and many more. Not every small library can afford to implement all the different details. However there are only a few http client libraries that are widely used between different projects, because of NIH or fears of vendor lock-in.
+
+## Goal
+
+This proposal aims at providing a very simple HTTP client interface to allow interopability between HTTP clients of different libraries and allow PHP libraries to ship HTTP client functionality without the necessity to implement a client.
+
+## Interfaces
+
+A single interface is proposed
+
+ <?php
+ namespace PSR\Http\Client;
+
+ /**
+ * A HTTP Client
+ */
+ interface HttpClient
+ {
+ /**
+ * Send a http-request and return a http-response.
+ *
+ * @param string $method HTTP method, uppercase
+ * @param string $url Url to send HTTP request to
+ * @param mixed $content Content of the request, can be empty.
+ * @param array $headers Array of Headers, header Name is the key.
+ * @param array $options Vendor specific options to activate specific features.
+ * @return Response
+ */
+ public function request($method, $url, $content = null, array $headers = array(), array $options = array());
+ }
+
+A value objects come with this interface, the Response which is returned from the client. Their definition is as follows:
+
+ <?php
+ namespace PSR\Http\Client;
+
+ /**
+ * Http Response returned from {@see HttpClient::request}.
+ */
+ class Response
+ {
+ /**
+ * Status code for the response
+ *
+ * @return int
+ */
+ public function getStatusCode();
+
+ /**
+ * Get content type for the response
+ *
+ * @return string
+ */
+ public function getContentType();
+
+ /**
+ * Get the content of this response
+ *
+ * @return string
+ */
+ public function getContent();
+
+ /**
+ * Return all headers of this response.
+ *
+ * @return array
+ */
+ public function getHeaders();
+
+ /**
+ * Return a specified header of this response or null if not found,
+ *
+ * Returns an array if multiple occurances of a header are returned.
+ *
+ * @return string|array|null
+ */
+ public function getHeader($name);
+ }
+
+## Sample code
+
+Here is an example usage:
+
+ <?php
+ $client = create_http_client(); // implementation specific
+ $response = $client->request('GET', 'http://www.php.net');
+
+ if ($response->getStatusCode() == 200) {
+ $content = $response->getContent();
+ }
+
+ $response = $client->request('GET', 'http://api/returning.json');
+
+ if ($response->getContentType() == 'application/json') {
+ $json = json_decode($response->getContent());
+ }
+

0 comments on commit 829ecc1

Please sign in to comment.