Merge pull request #39 from php-http/refactor

Refactor documentation

Author: sagikazarmark

docs/discovery.md renamed to docs/components/discovery.md

@@ -1,22 +1,27 @@
 # 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/client-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.
 
 Currently available discovery services:
 
 - HTTP Client Discovery
 - PSR-7 Message Factory Discovery
 - PSR-7 URI Factory Discovery
+- PSR-7 Stream 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.
 
-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.
 
 ## Installation
 
 ```
 $ composer require php-http/discovery
 ```
 
+
 ## HTTP Client Discovery
 
 This type of discovery finds an HTTP Client implementation.
@@ -42,6 +47,7 @@ class MyClass
 }
 ```
 
+
 ## HTTP Async Client Discovery
 
 This type of discovery finds a HTTP Async Client implementation.
@@ -67,9 +73,11 @@ class MyClass
 }
 ```
 
+
 ## PSR-7 Message Factory Discovery
 
-This type of discovery finds a [message factory](message-factory.md) for a [PSR-7](http://www.php-fig.org/psr/psr-7/) Message implementation.
+This type of discovery finds a [message factory](message-factory.md)
+for a [PSR-7](http://www.php-fig.org/psr/psr-7/) Message implementation.
 
 ``` php
 use Http\Message\MessageFactory;
@@ -95,7 +103,7 @@ class MyClass
 
 ## PSR-7 URI Factory Discovery
 
-This type of discovery finds a uri factory for a [PSR-7](http://www.php-fig.org/psr/psr-7/) URI implementation.
+This type of discovery finds a URI factory for a [PSR-7](http://www.php-fig.org/psr/psr-7/) URI implementation.
 
 ``` php
 use Http\Message\UriFactory;
@@ -121,14 +129,17 @@ class MyClass
 
 ## Integrating your own implementation with the discovery mechanism
 
-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:
+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
 HttpClientDiscovery::register('Acme\MyClient', true);
 ```
 
 - `class`: The class that is instantiated. This class MUST NOT require any constructor arguments.
-- `condition`: The condition that is evaluated to boolean to decide whether the class can be instantiated. The following types are allowed:
+- `condition`: The condition that is evaluated to boolean to decide whether the class can be instantiated.
+The following types are allowed:
     - string: Checked for class existence
     - callable: Called and evaluated to boolean
     - boolean: Can be true or false
@@ -141,8 +152,10 @@ Classes registered manually are put on top of the list.
 
 ### Writing your own discovery
 
-Each discovery service is based on the `ClassDiscovery` and has to specify a `cache` property and a `class` property to specify classes for the corresponding service.
-Since they are static, this properties need to be redeclared in each discovery class. If `ClassDiscovery` would declare them, they would be shared between the discovery classes which would make no sense.
+Each discovery service is based on the `ClassDiscovery` and has to specify a `cache` property and a `class` property
+to specify classes for the corresponding service. Since they are static, this properties need to be redeclared
+in each discovery class. If `ClassDiscovery` would declare them,
+they would be shared between the discovery classes which would make no sense.
 
 Here is an example discovery:
 

docs/components/message-factory.md

@@ -0,0 +1,26 @@
+# Message Factory
+
+**Factory interfaces for PSR-7 HTTP Message.**
+
+
+## Rationale
+
+While it should be possible to use every PSR-7 aware HTTP client with any RequestInterface implementation,
+creating the request objects will still tie the code to a specific implementation.
+If each reusable library is tied to a specific message implementation,
+an application could end up installing several message implementations.
+The factories abstract away from this.
+
+The FIG was pretty straightforward by NOT putting any construction logic into PSR-7.
+The `MessageFactory` aims to provide an easy way to construct messages.
+
+
+## Usage
+
+This package provides interfaces for PSR-7 factories including:
+
+- `MessageFactory`
+- `ServerRequestFactory` - WIP (PRs welcome)
+- `StreamFactory`
+- `UploadedFileFactory` - WIP (PRs welcome)
+- `UriFactory`

docs/httplug.md

@@ -0,0 +1,111 @@
+# HTTPlug HTTP client abstraction
+
+HTTPlug is an abstraction for HTTP clients. There are two main use cases:
+
+1. Usage in a project/application
+2. Usage in a reusable package
+
+In both cases, the `Http\Client\HttpClient` 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`.
+
+There is also the `Http\Client\HttpAsyncClient` which provides the `sendAsyncRequest` method to send
+a request asynchronously and returns a `Http\Client\Promise`.
+
+The promise allows to specify handlers for a PSR-7 `ResponseInterface`
+or an exception that implements `Http\Client\Exception`.
+
+
+<p class="text-warning">
+    Contract for the `Http\Client\Promise` is temporary until
+    [PSR is released](https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs).
+    Once it is out, we will use this PSR in the main client and deprecate the old contract.
+</p>
+
+
+See the [tutorial](tutorial.md) for a concrete example.
+
+
+## HTTPlug implementations
+
+HTTPlug implementations typically are either HTTP clients of their own, or adapters wrapping existing clients
+like Guzzle 6. In the latter case, they will depend on the required client implementation,
+so you only need to require the adapter and not the actual client.
+
+
+There are two kind of implementations:
+
+ - [php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation):
+ the synchronous implementation that waits for the response / error before returning from the `sendRequest` method.
+ - [php-http/async-client-implementation](https://packagist.org/providers/php-http/async-client-implementation):
+ the asynchronous implementation that immediately returns a `Http\Client\Promise`,
+ allowing to send several requests in parallel and handling responses later.
+
+Check links above for the full list of implementations.
+
+
+## Usage in an application
+
+When writing an application, you need to require a concrete
+[implementation](https://packagist.org/providers/php-http/client-implementation).
+
+See [virtual package](virtual-package.md) for more information on the topic of working with HTTPlug implementations.
+
+
+## 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.
+
+Reusable packages 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`
+or `php-http/async-client-implementation`. There is no package with that name,
+but all clients and adapters implementing HTTPlug declare that they provide one of this virtual package or both.
+
+You need to edit the `composer.json` of your package to add the virtual package.
+For development (installing the package standalone, running tests),
+add a concrete implementation in the `require-dev` section to make the project installable:
+
+``` json
+...
+"require": {
+    "php-http/client-implementation": "^1.0"
+},
+"require-dev": {
+    "php-http/guzzle6-adapter": "^1.0"
+},
+...
+```
+
+For extra convenience, you can use the [Discovery Component](/components/discovery) system to free the user of your
+package from having to instantiate the client.
+You should however always accept injecting the client instance to allow the user to configure the client as needed.
+You can find an example in the [Discovery Component](/components/discovery) documentation.
+
+Users of your package will have to select a concrete adapter in their project to make your package installable.
+Best point them to the [virtual package](virtual-package.md) howto page.
+
+To be able to send requests, you should not depend on a specific PSR-7 implementation,
+but use the [Message Factory Component](/components/message-factory) system.
+
+
+### Framework Integration
+
+HTTPlug can be used in any PHP based project.
+Nonetheless, we provide particular integration for some popular frameworks:
+
+- [HttplugBundle](https://github.com/php-http/HttplugBundle/) integration with the Symfony framework.
+
+
+## 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 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).
+
+In 2015, a decision has been made to move the library to it's own organization, so PHP HTTP was born.
+
+See [migrating](migrating.md) for a guide how to migrate your code from the Ivory adapter to HTTPlug.

docs/httplug/index.md

@@ -0,0 +1,31 @@
+# Migrating to HTTPlug
+
+If you currently use a concrete HTTP client implementation or the Ivory Http Adapter,
+migrating to Httplug should not be very hard.
+
+
+## Migrating from Ivory Http Adapter
+
+The monolithic ivory package has been separated into several smaller, more specific packages.
+
+Instead of `Ivory\HttpAdapter\PsrHttpAdapter`, use `Http\Client\HttpClient`.
+The HttpClient simply has a method to send requests.
+
+If you used the `Ivory\HttpAdapter\HttpAdapter`, have a look at the [Utilities](utils.md)
+and use the `Http\Client\Utils\HttpMethodsClient` which wraps any HttpClient and provides the convenience methods
+to send requests without creating RequestInterface instances.
+
+
+## Migrating from Guzzle
+
+Replace usage of `GuzzleHttp\ClientInterface` with `Http\Client\HttpClient`.
+The `send` method is called `sendRequest`.
+Instead of the `$options` argument, configure the client appropriately during set up.
+If you need different settings, create different instances of the client.
+You can use [plugins](plugins.md) to further tune your client.
+
+If you used the `request` method, have a look at the [Utilities](utils.md) and
+use the `Http\Client\Utils\HttpMethodsClient` which wraps any HttpClient and provides the convenience methods
+to send requests without creating RequestInterface instances.
+
+Asynchronous request support will land in HTTPlug soon.