Merge 4645b78 into 227784b

.gitattributes

@@ -0,0 +1,9 @@
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.travis.yml export-ignore
+/appveyor.yml export-ignore
+/CHANGELOG.md export-ignore
+/phpcs.xml.dist export-ignore
+/phpunit.xml.dist export-ignore
+/README.md export-ignore
+/tests export-ignore

.travis.yml

@@ -14,15 +14,6 @@ matrix:
       php: '7.3'
       env: require=1 dependencies=highest
 
-    - name: '[CS] PHP 7.2 With Locked Dependencies'
-      php: '7.2'
-      env: cs=1
-    - name: '[CS] PHP 7.2 With Lowest Dependencies'
-      php: '7.2'
-      env: cs=1 dependencies=lowest
-    - name: '[CS] PHP 7.2 With Highest Dependencies'
-      php: '7.2'
-      env: cs=1 dependencies=highest
     - name: '[CS] PHP 7.3 With Locked Dependencies'
       php: '7.3'
       env: cs=1
@@ -38,71 +29,70 @@ matrix:
     - name: '[CS] PHP Nightly With Lowest Dependencies'
       php: nightly
       env: cs=1 dependencies=lowest
-    - name: '[CS] PHP Nightly With HIghest Dependencies'
+    - name: '[CS] PHP Nightly With Highest Dependencies'
       php: nightly
       env: cs=1 dependencies=highest
 
-    - name: '[UNIT] PHP 7.2 With Locked Dependencies'
-      php: '7.2'
-    - name: '[UNIT] PHP 7.2 With Lowest Dependencies'
-      php: '7.2'
-      env: dependencies=lowest
-    - name: '[UNIT] PHP 7.2 With Highest Dependencies'
-      php: '7.2'
-      env: dependencies=highest
     - name: '[UNIT] PHP 7.3 With Locked Dependencies'
       php: '7.3'
+      env: unit=1
     - name: '[UNIT] PHP 7.3 With Lowest Dependencies'
       php: '7.3'
-      env: dependencies=lowest
+      env: dependencies=lowest unit=1
     - name: '[UNIT] PHP 7.3 With Highest Dependencies'
       php: '7.3'
-      env: dependencies=highest
+      env: dependencies=highest unit=1
     - name: '[UNIT] PHP Nightly With Locked Dependencies'
       php: nightly
+      env: unit=1
     - name: '[UNIT] PHP Nightly With Highest Dependencies'
       php: nightly
-      env: dependencies=lowest
+      env: dependencies=highest unit=1
     - name: '[UNIT] PHP Nightly With Lowest Dependencies'
       php: nightly
-      env: dependencies=highest
+      env: dependencies=lowest unit=1
   allow_failures:
     - name: '[CS] PHP Nightly With Locked Dependencies'
       php: nightly
       env: cs=1
     - name: '[CS] PHP Nightly With Lowest Dependencies'
       php: nightly
       env: cs=1 dependencies=lowest
-    - name: '[CS] PHP Nightly With HIghest Dependencies'
+    - name: '[CS] PHP Nightly With Highest Dependencies'
       php: nightly
       env: cs=1 dependencies=highest
 
     - name: '[UNIT] PHP Nightly With Locked Dependencies'
       php: nightly
+      env: unit=1
     - name: '[UNIT] PHP Nightly With Highest Dependencies'
       php: nightly
-      env: dependencies=lowest
+      env: dependencies=highest unit=1
     - name: '[UNIT] PHP Nightly With Lowest Dependencies'
       php: nightly
-      env: dependencies=highest
+      env: dependencies=lowest unit=1
+
+services:
+  - redis-server
 
 before_install:
-- phpenv config-rm xdebug.ini || echo "No xdebug config."
-- composer self-update
+  - phpenv config-rm xdebug.ini || echo "No xdebug config."
+  - composer self-update
 
 install:
-- wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.0.0/php-coveralls.phar
-- chmod +x php-coveralls.phar
+  - wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.0.0/php-coveralls.phar
+  - chmod +x php-coveralls.phar
 
 before_script:
-  - if [ -z "$dependencies" ]; then travis_retry composer install --no-scripts; fi;
-  - if [ "$dependencies" = "lowest" ]; then travis_retry composer update --no-scripts --prefer-lowest -n; fi;
-  - if [ "$dependencies" = "highest" ]; then travis_retry composer update --no-scripts -n; fi;
+  - if [ -z "$dependencies" ]; then travis_retry composer install -n; fi;
+  - if [ "$dependencies" = "lowest" ]; then travis_retry composer update --prefer-lowest -n; fi;
+  - if [ "$dependencies" = "highest" ]; then travis_retry composer update -n; fi;
 
 script:
-  - if [ -z "$cs" ] && [ -z "$require" ]; then phpdbg -qrr vendor/bin/phpunit --coverage-text --coverage-clover build/logs/clover.xml; fi;
+  - if [ "$unit" = 1 ]; then phpdbg -qrr vendor/bin/phpunit --testsuite HarmonIOHttpClientUnitTestSuite --coverage-text --coverage-clover build/logs/clover.xml; fi;
+  - if [ "$integration" = 1 ]; then phpdbg -qrr vendor/bin/phpunit --testsuite HarmonIOHttpClientIntegrationTestSuite --coverage-text --coverage-clover build/logs/clover.xml; fi;
   - if [ "$cs" = 1 ]; then vendor/bin/phpcs -s; fi;
   - if [ "$require" = 1 ]; then vendor/bin/composer-require-checker check; fi;
 
 after_success:
-  - if [ -z "$cs" ] && [ -z "$require" ]; then travis_retry php php-coveralls.phar; fi;
+  - if [ "$unit" = 1 ]; then travis_retry php php-coveralls.phar; fi;

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] - 0000-00-00
+
+### Added
+
+*None*
+
+### Changed
+
+*None*
+
+### Deprecated
+
+*None*
+
+### Removed
+
+*None*
+
+### Fixed
+
+*None*
+
+### Security
+
+*None*

README.md

@@ -5,3 +5,137 @@
 [![Build status](https://ci.appveyor.com/api/projects/status/qe3volxj5pxqaguu/branch/master?svg=true)](https://ci.appveyor.com/project/PeeHaa/http-client/branch/master)
 [![Coverage Status](https://coveralls.io/repos/github/HarmonyIO/Http-Client/badge.svg?branch=master)](https://coveralls.io/github/HarmonyIO/Http-Client?branch=master)
 [![License](https://poser.pugx.org/harmonyio/http-client/license)](https://packagist.org/packages/harmonyio/http-client)
+
+Async caching aware http client
+
+## Requirements
+
+- PHP 7.3
+- Redis (if wanting to use the Redis caching provider)
+
+In addition for non-blocking context one of the following event libraries should be installed:
+
+- [ev](https://pecl.php.net/package/ev)
+- [event](https://pecl.php.net/package/event)
+- [php-uv](https://github.com/bwoebi/php-uv)
+
+## Installation
+
+```
+composer require harmonyio/http-client
+```
+
+## Usage
+
+### Caching requests
+
+The following example shows how to make a request and cache the result so consecutive calls will used the cached results instead of making a new external HTTP call.
+
+```php
+<?php declare(strict_types=1);
+
+namespace Foo;
+
+use Amp\Artax\DefaultClient;
+use Amp\Redis\Client;
+use HarmonyIO\Cache\Provider\Redis;
+use HarmonyIO\Cache\Ttl;
+use HarmonyIO\HttpClient\Client\ArtaxClient;
+use HarmonyIO\HttpClient\Message\CachingRequest;
+use function Amp\wait;
+
+// create instance of the HTTP client
+$httpClient = new ArtaxClient(
+    new DefaultClient(),
+    new Redis(new Client('tcp://127.0.0.1:6379'))
+);
+
+// create a new request to be cached for 10 seconds
+$request = new CachingRequest('TestRequestKey', new Ttl(10), 'https://httpbin.org/get');
+
+// make the request and cache it
+$result = wait($httpClient->request($request));
+
+// all consecutive requests will now used the cached result instead of calling the external service again
+$result = wait($httpClient->request($request));
+```
+
+### Non-caching requests
+
+It is also possible to make non-caching requests.
+
+```php
+<?php declare(strict_types=1);
+
+namespace Foo;
+
+use Amp\Artax\DefaultClient;
+use Amp\Redis\Client;
+use HarmonyIO\Cache\Provider\Redis;
+use HarmonyIO\HttpClient\Client\ArtaxClient;
+use HarmonyIO\HttpClient\Message\Request;
+use function Amp\wait;
+
+// create instance of the HTTP client
+$httpClient = new ArtaxClient(
+    new DefaultClient(),
+    new Redis(new Client('tcp://127.0.0.1:6379'))
+);
+
+// create a new request to be cached for 10 seconds
+$request = new Request('https://httpbin.org/get');
+
+// make the request (the results will NOT be cache)
+$result = wait($httpClient->request($request));
+
+// make the same request again
+$result = wait($httpClient->request($request));
+```
+
+## Client interface
+
+The HTTP client's interface only contains a single method: `Client::request(\HarmonyIO\HttpClient\Message\Request $request)`.
+
+The `$request` parameter can be either a "normal" non-caching request (`HarmonyIO\HttpClient\Message\Request`) or a caching request (`HarmonyIO\HttpClient\Message\CachingRequest`).
+
+### `HarmonyIO\HttpClient\Message\Request`
+
+The constructor of the request class expects at least a URL to make the request to and optionally an HTTP method (defaults to GET).
+
+Optional request parts can be set in setter method of the request class:
+
+```php
+<?php declare(strict_types=1);
+
+namespace Foo;
+
+use HarmonyIO\HttpClient\Message\Request;
+
+$request = (new Request('https://httpbin.org/post', 'POST'))
+    ->setProtocolVersions('1.1', '2.0')
+    ->addHeader('foo', 'bar')
+    ->addHeader('baz', 'qux')
+    ->setBody('foobar')
+;
+```
+
+### `HarmonyIO\HttpClient\Message\CachingRequest`
+
+The constructor of the caching request class expects at least a key, a TTL, the URL to make the request to and optionally an HTTP method (defaults to GET).
+
+Optional request parts can be set in setter method of the request class as defined in the previous section.
+
+```php
+<?php declare(strict_types=1);
+
+namespace Foo;
+
+use HarmonyIO\Cache\Ttl;
+use HarmonyIO\HttpClient\Message\CachingRequest;
+
+$request = (new CachingRequest('UniqueCachingKey', new Ttl(Ttl::ONE_HOUR), 'https://httpbin.org/get'))
+    ->setProtocolVersions('1.1', '2.0')
+    ->addHeader('foo', 'bar')
+    ->addHeader('baz', 'qux')
+;
+```