-
Notifications
You must be signed in to change notification settings - Fork 56
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit e73b895
Showing
6 changed files
with
215 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
Copyright (c) 2014-2015 Eric GELOEN <geloen.eric@gmail.com> | ||
|
||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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** |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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(); | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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_ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
site_name: HTTP Adapter Documentation |