Merge pull request #8 from teresko/master

API changes for interacting with cookies + starting to write docs

README.md

@@ -3,21 +3,72 @@
 
 [![Build Status](https://travis-ci.org/fracture/http.png?branch=master)](https://travis-ci.org/fracture/http)
 [![Code Coverage](https://scrutinizer-ci.com/g/fracture/http/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/fracture/http/?branch=master)
-[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fracture/http/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/fracture/http/?branch=master)
+[![Scrutinizer](https://img.shields.io/scrutinizer/g/fracture/http.svg)](https://scrutinizer-ci.com/g/fracture/http/?branch=master)
+[![Packagist](https://img.shields.io/packagist/v/fracture/http.svg)](https://packagist.org/packages/fracture/http)
 
 ## Introduction
 
-The primary goal is to create a simple abstraction for handling the HTTP interaction.
+A simple abstraction for handling the HTTP request and responses. Library is made for interacting with [Fracture\Routing](https://github.com/fracture/http) and provides simple object-oriented abstractions.
 
-Library is made for interacting with Fracture\Routing. In addition to the implemented interface,
-it also provides object-oriented abstractions for the following functionality:
+## Installation
 
-- file uploads
-- cookies
-- headers (some of them)
+You can add the library to your project using composer with following command:
 
-## Instalation
+```sh
+    composer require fracture/http
+```
 
-Since the library is still in development, the recommended version to install would be "the latest". You can do it by running following command:
 
-    composer require fracture/http:dev-master
+##Usage
+
+All of the following code will assume that the Composer's autoloader has already been included.
+
+###Basic request initialization
+
+While initializing a new `Request` instance manually is possible, for the instance to be fully prepared, it require several additional steps. For this reason it's better to use the `RequestBuider`, that will those steps:
+
+```php
+<?php
+// -- unimportant code above --
+
+$builder = new Fracture\Http\RequestBuilder;
+$request = $builder->create([
+    'get'    => $_GET,
+    'files'  => $_FILES,
+    'server' => $_SERVER,
+    'post'   => $_POST,
+    'cookies'=> $_COOKIE,
+]);
+```
+
+Use of this code fragment is sufficient for any basic website and will produces a ready-to-use `Request` instance.
+
+###Requests and REST
+
+When creating a site, that provides REST API, a common practice is to implement API versioning via HTTP Accept and Content-Type headers. To retrieve data, which was sent with a custom Content-Type header, you define a parser, which, if the media type matches, is executed to supplement the `Request` instance with additional parameters.
+
+```php
+<?php
+// -- unimportant code above --
+
+$builder = new Http\RequestBuilder;
+$builder->addContentParser('application/json', function () {
+    $data =  json_decode(file_get_contents('php://input'), true);
+
+    if ($data === null) {
+        $data = [];
+    }
+
+    return $data;
+});
+$request = $builder->create([
+    'server' => $_SERVER,
+    'cookies'=> $_COOKIE,
+]);
+```
+
+The parser itself is defined as an anonymous function, which will be called with `Fracture\Http\Headers\ContentType` as the parameter and is expected to return an array of `name => value` pairs for parameters.
+
+```php
+array function([Fracture\Http\Headers\ContentType $header])
+```

src/Fracture/Http/Headers/Accept.php

@@ -264,7 +264,7 @@ private function isMatch(array $left, array $right)
 
     /**
      * @param string $target
-     * @param string pattern
+     * @param string $pattern
      * @return string
      */
     private function replaceStars($target, $pattern)

src/Fracture/Http/Headers/SetCookie.php

@@ -10,7 +10,8 @@ class SetCookie implements Abstracted
     protected $headerValue = null;
     protected $headerName = 'Set-Cookie';
 
-    private $cookie = null;
+    private $cookieName = null;
+    private $cookieValue = null;
     private $options = [];
 
     private $defaults = [
@@ -22,9 +23,10 @@ class SetCookie implements Abstracted
     ];
 
 
-    public function __construct(Cookie $cookie, $options = [])
+    public function __construct($name, $value, $options = [])
     {
-        $this->cookie = $cookie;
+        $this->cookieName = $name;
+        $this->cookieValue = $value;
         $this->options = $options;
     }
 
@@ -98,8 +100,8 @@ public function getName()
 
     public function getValue()
     {
-        $name = urlencode($this->cookie->getName());
-        $value = urlencode($this->cookie->getValue());
+        $name = urlencode($this->cookieName);
+        $value = urlencode($this->cookieValue);
 
         $result = "{$name}={$value}" . $this->collectFormatedOptions();
 

src/Fracture/Http/Request.php

@@ -155,10 +155,9 @@ public function getUpload($name)
     }
 
 
-    public function addCookie($cookie)
+    public function addCookie($name, $value)
     {
-        $name = $cookie->getName();
-        $this->cookies[$name] = $cookie;
+        $this->cookies[$name] = $value;
     }
 
 

src/Fracture/Http/RequestBuilder.php

@@ -18,7 +18,7 @@ class RequestBuilder
 
     /**
      * @param array[] $params
-     * @return \Fracture\Routing\Routable
+     * @return Routable
      */
     public function create($params)
     {
@@ -68,22 +68,26 @@ protected function applyContentParsers($instance)
             return;
         }
 
-        foreach ($this->parsers as $value => $parser) {
-            if ($header->contains($value)) {
-                $parameters += $this->alterParameters($parser, $value, $header);
+        foreach ($this->parsers as $type => $parser) {
+            if ($header->contains($type)) {
+                $parameters += $this->alterParameters($parser, $type, $header);
             }
         }
 
         $instance->setParameters($parameters, true);
     }
 
-
-    private function alterParameters($parser, $value, $header)
+    /**
+     * @param callable $parser
+     * @param string $type
+     * @param Headers\ContentType $header
+     */
+    private function alterParameters($parser, $type, $header)
     {
         $result = call_user_func($parser, $header);
 
         if (false === is_array($result)) {
-            $message = "Parser for '$value' did not return a 'name => value' array of parameters";
+            $message = "Parser for '$type' did not return a 'name => value' array of parameters";
             trigger_error($message, \E_USER_WARNING);
         }
 
@@ -104,7 +108,7 @@ protected function applyParams($instance, $params)
         $this->applyWebContext($instance, $params['server']);
 
         foreach ($params['cookies'] as $name => $value) {
-            $instance->addCookie(new Cookie($name, $value));
+            $instance->addCookie($name, $value);
         }
     }
 
@@ -128,7 +132,7 @@ protected function applyWebContext($instance, $params)
      * @param Request $instance
      * @param array $params
      */
-    public function applyHeaders($instance, $params)
+    protected function applyHeaders($instance, $params)
     {
         if (array_key_exists('HTTP_ACCEPT', $params)) {
             $header = new Headers\Accept($params['HTTP_ACCEPT']);

src/Fracture/Http/Response.php

@@ -48,18 +48,17 @@ public function getBody()
     }
 
 
-    public function addCookie(Cookie $cookie, $options = [])
+    public function addCookie($name, $value, $options = [])
     {
-        $header = new Headers\SetCookie($cookie, $options);
+        $header = new Headers\SetCookie($name, $value, $options);
         $header->prepare();
-        $this->cookies[$cookie->getName()] = $header;
+        $this->cookies[$name] = $header;
     }
 
 
     public function removeCookie($name, $options = [])
     {
-        $cookie = new Cookie($name, 'deleted');
-        $this->addCookie($cookie, ['expires' => 0] + $options);
+        $this->addCookie($name, 'deleted', ['expires' => 0] + $options);
     }