reorganizing the documentation

Author: dbu

README.md

@@ -1,8 +1,8 @@
-# HTTP Adapter Documentation
+# PHP-HTTP 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**
+**This is the documentation repository of the PHP-HTTP software components**
 
 Browse the documentation on [Read the Docs](http://php-http.readthedocs.org/).

docs/discovery.md

@@ -1,57 +1,46 @@
 # Discovery
 
-The discovery service is a set of static classes which allows to find and use installed resources. This is useful in libraries that want to offer zero-configuration services and rely only on the virtual packages, e.g. `php-http/adapter-implementation` or `psr/http-message-implementation`.
+The discovery service is a set of static classes which allows to find and use installed resources. This is useful in libraries that want to offer zero-configuration services and rely only on the virtual packages, e.g. `php-http/client-implementation` or `psr/http-message-implementation`.
 
 
 Currently available discovery services:
 
-- HTTP Adapter Discovery
+- HTTP client Discovery
 - PSR-7 Message Factory Discovery
 - PSR-7 URI Factory Discovery
 
 The principle is always the same: you call the static `find` method on the discovery service if no explicit implementation was specified. The discovery service will try to locate a suitable implementation. If no implementation is found, an `Http\Discovery\NotFoundException` is thrown.
 
 
-## HTTP Adapter Discovery
+## HTTP Client Discovery
 
-This type of discovery finds installed HTTP Adapters.
-
-Currently available adapters:
-
-- [Guzzle 6](https://github.com/php-http/guzzle6-adapter)
-- [Guzzle 5](https://github.com/php-http/guzzle5-adapter)
+This type of discovery finds installed HTTP Clients.
 
 ``` php
-use Http\Adapter\HttpAdapter;
-use Http\Discovery\HttpAdapterDiscovery;
+use Http\Client\HttpClient;
+use Http\Discovery\HttpClientDiscovery;
 
 class MyClass
 {
     /**
-     * @var HttpAdapter
+     * @var HttpClient
      */
-    protected $httpAdapter;
+    protected $httpClient;
 
     /**
-     * @param HttpAdapter|null $httpAdapter to do HTTP requests.
+     * @param HttpClient|null $httpClient to do HTTP requests.
      */
-    public function __construct(HttpAdapter $httpAdapter = null)
+    public function __construct(HttpClient $httpClient = null)
     {
-        $this->httpAdapter = $httpAdapter ?: HttpAdapterDiscovery::find();
+        $this->httpClient = $httpClient ?: HttpClientDiscovery::find();
     }
 }
 ```
 
 
 ## PSR-7 Message Factory Discovery
 
-This type of discovery finds installed [PSR-7](http://www.php-fig.org/psr/psr-7/) Message implementations and their factories.
-
-Currently available factories:
-
-- [Guzzle](https://github.com/guzzle/psr7) factory
-- [Diactoros](https://github.com/zendframework/zend-diactoros) factory
-
+This type of discovery finds installed [PSR-7](http://www.php-fig.org/psr/psr-7/) Message implementations and their (factories)[message-factory.md].
 
 ``` php
 use Http\Message\MessageFactory;
@@ -74,16 +63,11 @@ class MyClass
 }
 ```
 
+
 ## PSR-7 URI Factory Discovery
 
 This type of discovery finds installed [PSR-7](http://www.php-fig.org/psr/psr-7/) URI implementations and their factories.
 
-Currently available factories:
-
-- [Guzzle](https://github.com/guzzle/psr7) factory
-- [Diactoros](https://github.com/zendframework/zend-diactoros) factory
-
-
 ``` php
 use Http\Message\UriFactory;
 use Http\Discovery\UriFactoryDiscovery;
@@ -111,7 +95,7 @@ class MyClass
 The `php-http/discovery` has built-in support for some implementations. To use a different implementation or override the default when several implementations are available in your codebase, you can register a class explicitly with the corresponding discovery service. For example:
 
 ``` php
-HttpAdapterDiscovery::register('Acme\MyAdapter', true);
+HttpClientDiscovery::register('Acme\MyClient', true);
 ```
 
 - `class`: The class that is instantiated. This class MUST NOT require any constructor arguments.

docs/httplug.md

@@ -0,0 +1,51 @@
+# Httplug HTTP client abstraction
+
+Httplug is an abstraction for HTTP clients. There are two main use cases:
+
+1. Usage in a project
+2. Usage in a reusable package
+
+In both cases, the client provides a `sendRequest` method to send a PSR-7 `RequestInterface` and returns a PSR-7 `ResponseInterface` or throws an exception that implements `Http\Client\Exception`. The client also has a `sendRequests` to send requests in parallel. Clients that do not support sending requests in parallel will just send them sequentially.
+
+See the (tutorial)[tutorial.md] for a concrete example.
+
+## Httplug implementations
+
+Httplug implementations typically are either HTTP clients of their own, or they are adapters wrapping existing clients like Guzzle 6. In the later case, they will depend on the required client implementation, you should only need to require the adapter and not the actual client.
+
+Clients usually also provide a (message factory)[message-factory.md] to allow you to create requests. See https://packagist.org/providers/php-http/client-implementation for the full list of implementations.
+
+Note: Until Httplug 1.0 becomes stable, we will focus on the Guzzle6 adapter.
+
+## Usage in a project
+
+When installing in an application or a non-reusable package, you should require a concrete client implementation. The client will in turn depend on `php-http/httplug`.
+
+A few things should be taken into consideration before choosing an adapter:
+
+- It is possible that some other dependency already has an HTTP Client requirement like Guzzle 6. It can be confusing to have more than one HTTP Client installed, so always check your other requirements and choose an adapter based on that.
+- Some clients support parallel requests, others only emulate them. If parallel requests are needed, use one which supports it.
+
+
+## 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, they should **not rely on a concrete implementation** (like Guzzle 6), but only require any implementation of Httplug. Httplug uses the concept of virtual packages. Instead of depending on only the interfaces, which would be missing an implementation, or depending on one concrete implementation, you should depend on the virtual package `php-http/client-implementation`. There is no package with that name, but all clients and adapters implementing Httplug declare that they provide this virtual package.
+
+With Composer, it is possible:
+
+``` bash
+composer require "php-http/client-implementation" "^1.0"
+```
+
+This allows the end user to choose the concrete implementation when they are install the package. During development and for running tests, a concrete implementation is needed. Use the `require-dev` section of composer:
+
+
+``` bash
+composer require --dev "php-http/guzzle6-adapter" "^1.0"
+```
+
+If injecting the client instance into the code of the reusable package is not convenient, you can use the (Discovery)[discovery.md] system.
+
+Users of your package will have to select a concrete adapter in their project to make your package installable.

docs/index.md

@@ -1,87 +1,34 @@
 # HTTP Adapter
 
-**This is the documentation for HTTP Adapter and it's software components.**
+**This is the documentation for the Httplug web client abstraction and the other PHP-HTTP components.**
 
-The HTTP Adapter abstracts from PHP HTTP clients that are based on [PSR-7](http://www.php-fig.org/psr/psr-7/).
+Httplug abstracts from HTTP clients written in PHP that are based on [PSR-7](http://www.php-fig.org/psr/psr-7/).
 It allows you to write reusable libraries and applications that need a HTTP client without binding to a specific implementation.
 
-## 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. Because of the constantly changing PSR-7 Eric had to rewrite the library over and over again (at least the message handling part, which in most cases affected every adapters).
-
-in 2015 a decision has been made to move the library to it's own organization, so PHP HTTP was born.
+If you do not have access to a dependency injection system, the [Discovery](discovery.md) system can be used to automatically locate a suitable client and a PSR-7 message factory. 
 
 
 ## 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
-```
-
+Read our [tutorial](tutorial.md).
 
-#### 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.
+## Overview
 
-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:
+PHP-HTTP is separated into several packages:
 
-``` json
-{
-    "require": {
-        "php-http/adapter-implementation": "^1.0"
-    }
-}
-```
+- [Httplug](httplug.md), the HTTP client abstraction to send PSR-7 requests without binding to a specific implementation;
+- [Message Factory](message-factory.md) to create PSR-7 requests without binding to a specific implementation; 
+- [Discovery](discovery.md) to automatically locate a suitable Httplug implementation and PSR-7 message factory.
+- [Utilities](utils.md) for convenient sending of HTTP requests.
 
-This allows the end user to choose a concrete implementation when installs the package. Of course, during development a concrete implementation is needed:
+See (package overview)[package-overview.md] for a complete list.
 
 
-``` 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, requiring the 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 can be confusing to have more than one HTTP Client installed, so always check your other requirements and choose an adapter based on that.
-- Some adapters support parallel requests, some only emulate them. If parallel requests are needed, use one which supports it.
+## History
 
-Installing an implementation is easy:
+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 a stable release, but it relied on PSR-7 which was not stable either that time. Because of the constantly changing PSR-7, Eric had to rewrite the library over and over again (at least the message handling part, which in most cases affected every adapter as well).
 
-``` bash
-$ composer require php-http/*-adapter
-```
+In 2015, a decision has been made to move the library to it's own organization, so PHP HTTP was born.
 
-_Replace * with any supported adapter name_
+See (upgrading)[upgrading.md] for a guide how to migrate your code from the Ivory adapter to Httplug.

docs/message-factory.md

@@ -22,6 +22,7 @@ This package provides interfaces for PSR-7 factories including:
 
 A virtual package ([php-http/message-factory-implementation](https://packagist.org/providers/php-http/message-factory-implementation)) MAY be introduced which MUST be versioned together with this package.
 
+The adapter repositories provide wrapper classes for those factories to implement the `Http\Message\MessageFactory` interface.
 
 ### General usage
 

docs/package-overview.md

@@ -0,0 +1,44 @@
+# Overview of PHP-HTTP packages
+
+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/).
+
+## httplug
+
+**Interfaces for HTTP Client**
+
+- Namespace: `Http\Client`
+- Repository: https://github.com/php-http/httplug
+- Documentation: (Httplug)[httplug.md]
+
+## message-factory
+
+**Abstraction to create PSR-7 requests without binding to a specific implementation**
+ 
+- Namespace: `Http\Message`
+- Repository: https://github.com/php-http/message-factory
+- Documentation: [Message Factory](message-factory.md) 
+
+## *-adapter
+
+**Each adapter is separated into its own package. This allows to make requirements to the underlying HTTP Client libraries.**
+
+- Namespace: `Http\Adapter`
+- Repository: https://github.com/php-http/*-adapter
+
+For a full list, see https://github.com/php-http/
+
+## discovery
+
+**Discovery service to find installed resources (httplug implementation, message factory)**
+
+- Namespace: `Http\Discovery`
+- Repository: https://github.com/php-http/discovery
+- Documentation: (Discovery)[discovery.md]
+
+## utils
+
+**Utility classes for HTTP consumers**
+
+- Namespace: `Http\Utils`
+- Repository: https://github.com/php-http/utils
+- Documentation: (Utils)[utils.md]

docs/tutorial.md

@@ -0,0 +1,46 @@
+# Httplug tutorial
+
+This tutorial should give you an idea how to use Httplug in your project. Httplug has two main use cases:
+
+1. Usage in your project;
+2. Usage in a reusable package.
+
+This tutorial will start with the first use case and then explain the special considerations to take into account when building a reusable package.
+
+We use (composer)[https://getcomposer.org] for dependency management. Install it if you don't have it yet.
+
+## Setting up the project
+
+``` bash
+mkdir httplug-tutorial
+cd httplug-tutorial
+composer init
+# specify your information as you want. say no to defining the dependencies interactively
+composer require php-http/guzzle6-adapter
+```
+
+The last command will install Guzzle as well as the Guzzle Httplug adapter and the required interface repositories. We are now ready to start coding.
+
+## Writing some simple code
+
+Create a file `demo.php` in the root folder and write the following code:
+
+``` php
+<?php
+require('vendor/autoload.php');
+
+TODO: create client instance with discovery and do some requests
+```
+
+## Handling errors
+
+TODO: explain how to handle exceptions, distinction between network exception and HttpException.
+
+## Doing parallel requests
+
+TODO explain sendRequests and how to work with BatchResult and BatchException
+
+
+## Writing a reusable package
+
+TODO: explain the virtual package