Initial commit

Author: sagikazarmark

.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+
+[*.yml*]
+indent_style = space
+indent_size = 2

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2014-2015 Eric GELOEN <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,6 @@
+# HTTP Adapter Documentation
+
+[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
+
+
+**This is the documentation repository of the HTTP Adapter software components**

docs/discovery.md

@@ -0,0 +1,93 @@
+# Discovery
+
+The discovery service is a set of static classes which allows to find and use installed resources. This is especially useful when used with some virtual packages providing an implementation (`php-http/adapter-implementation`, `psr/http-message-implementation`).
+
+
+Currently available discovery services:
+
+- HTTP Adapter Discovery
+- PSR Message Discovery
+- PSR URI Discovery
+
+
+## General
+
+Discoveries in general are really similar. In fact, the code behind them is exactly the same.
+
+Here is an example dummy discovery:
+
+``` php
+use Http\Discovery\ClassDiscovery;
+
+class MyDiscovery extends ClassDiscovery
+{
+    // IMPORTANT: not declared in the parent to avoid overwritting
+    protected static $cache;
+
+    // IMPORTANT: not declared in the parent
+    protected static $classes = [];
+}
+```
+
+A start value can be defined for the `classes` property in the following structure:
+
+``` php
+[
+    'name' => [
+        'class'     => 'MyClass',
+        'condition' => 'MyCondition',
+    ],
+]
+```
+
+- `name`: A unique name for the resource, can be overwritten using `register`
+- `class`: The class that is instantiated. There MUST NOT be any constructor arguments.
+- `condition`: The condition that is evaluated to boolean to decide whether the resource is available. The following types are allowed:
+    - string: Checked for class existence
+    - callable: Called and evaluated to boolean
+    - boolean: Evaluated as is
+    - any other: evaluated to false
+
+By declaring a start value for `classes` only string conditions are allowed, however the `register` method allows any type of arguments:
+
+``` php
+MyDiscovery::register('name', 'MyClass', true);
+```
+
+The condition can also be omitted. In that case the class is used as the condition (to check for existence).
+
+The last thing to do is to find the first available resource:
+
+```php
+$myClass = MyDiscovery::find();
+```
+
+If no classes can be found, an `Http\Discovery\NotFoundException` is thrown.
+
+
+## HTTP Adapter Discovery
+
+This type of discovery finds installed HTTP Adapters.
+
+It is useful to provide zero-configuration for classes relying on an adapter:
+
+``` php
+use Http\Adapter\HttpAdapter;
+use Http\Discovery\HttpAdapterDiscovery;
+
+class MyClass
+{
+    /**
+     * @var HttpAdapter
+     */
+    protected $httpAdapter;
+
+    /**
+     * @param HttpAdapter $httpAdapter
+     */
+    public function __construct(HttpAdapter $httpAdapter)
+    {
+        $this->httpAdapter = $httpAdapter ?: HttpAdapterDiscovery::find();
+    }
+}
+```

docs/index.md

@@ -0,0 +1,83 @@
+# HTTP Adapter
+
+**This is the documentation for HTTP Adapter and it's software components.**
+
+
+## History
+
+This project has been started by [Eric Geloen](https://github.com/egeloen) as [Ivory Http Adapter](https://github.com/egeloen/ivory-http-adapter). It never made it to be really stable, but it relied on PSR-7 which was not stable either that time.
+
+
+## Getting started
+
+HTTP Adapter is separated into several components:
+
+- Adapter contract
+- Client contract
+- Adapter client
+- Adapter implementations
+- Helpers
+
+
+### Installation
+
+There are many strategies how adapters and other components can be installed. However they are the same in one thing: they can be installed via [Composer](http://getcomposer.org/):
+
+``` bash
+$ composer require php-http/adapter
+```
+
+
+#### Installation in a reusable package
+
+In many cases packages are designed to be reused from the very beginning. For example API clients are usually used in other packages/applications, not on their own.
+
+In these cases it is always a good idea not to rely on a concrete implementation (like Guzzle), but only require some implementation of an HTTP Adapter. With Composer, it is possible:
+
+``` json
+{
+    "require": {
+        "php-http/adapter-implementation": "^1.0"
+    }
+}
+```
+
+This allows the end user to choose a concrete implementation when installs the package. Of course, during development a concrete implementation is needed:
+
+
+``` json
+{
+    "require-dev": {
+        "php-http/guzzle6-adapter": "^1.0"
+    }
+}
+```
+
+
+Another good practice if the package works out-of-the-box, no or only minimal configuration is needed. While not requiring a concrete implementation is great, it also means that the end user would have to always inject the installed adapter (which is the right, but not a convenient solution). To solve this, there is a discovery components which finds and resolves other installed components:
+
+``` json
+{
+    "require": {
+        "php-http/discovery": "^1.0"
+    }
+}
+```
+
+Read more about it in the [Discovery](discovery.md) part.
+
+
+#### Installation in an end user package
+
+When installing in an application or a non-reusable package, using a virtual package doesn't really make sense. However there are a few things which should be taken into consideration before choosing an adapter:
+
+- It is possible that some other package already has an HTTP Client requirement. It doesn't worth to install more than one HTTP Clients.
+- Some adapters support paralell requests, some only emulate them. If paralell requests are needed, use one which supports it.
+
+Installing an implementation is easy:
+
+``` bash
+$ composer require php-http/*-adapter
+```
+
+_Replace * with any supported adapter name_

mkdocs.yml

@@ -0,0 +1 @@
+site_name: HTTP Adapter Documentation