PSR-7 Implementation Decoupling

.travis.yml

@@ -6,26 +6,26 @@ dist: trusty
 
 matrix:
   include:
-    - php: 7.0
-    - php: 7.0
-      env: COMPOSER_ARGS='--prefer-lowest'
-    - php: 7.1
-      env: ANALYSIS='true'
-    - php: 7.2
-    - php: nightly
+  - php: 7.1
+    env: ANALYSIS='true'
+  - php: 7.2
+  - php: 7.3
+  - php: nightly
   allow_failures:
-    - php: nightly
+  - php: nightly
 
 before_script:
-  - composer update $COMPOSER_ARGS
+- composer require php-coveralls/php-coveralls:^2.1.0
+- composer install -n
 
 script:
-  - if [[ "$ANALYSIS" != 'true' ]]; then vendor/bin/phpunit ; fi
-  - if [[ "$ANALYSIS" == 'true' ]]; then vendor/bin/phpunit --coverage-clover clover.xml ; fi
-  - if [[ "$ANALYSIS" == 'true' ]]; then vendor/bin/phpcs ; fi
+- if [[ "$ANALYSIS" == 'true' ]]; then vendor/bin/phpunit --coverage-clover clover.xml ; fi
+- vendor/bin/phpunit
+- vendor/bin/phpcs
+- vendor/bin/phpstan analyse Slim
 
-after_script:
-  - if [[ "$ANALYSIS" == 'true' ]]; then php vendor/bin/coveralls --coverage_clover=clover.xml -v ; fi
+after_success:
+- if [[ "$ANALYSIS" == 'true' ]]; then vendor/bin/php-coveralls --coverage_clover=clover.xml -v ; fi
 
 notifications:
   slack: slimphp:0RNzx2JuhkAqIf0MXcUZ0asT

README.md

@@ -15,24 +15,166 @@ It's recommended that you use [Composer](https://getcomposer.org/) to install Sl
 $ composer require slim/slim "^4.0"
 ```
 
-This will install Slim and all required dependencies. Slim requires PHP 7.0.0 or newer.
+This will install Slim and all required dependencies. Slim requires PHP 7.1 or newer.
 
-## Usage
+## Choose a PSR-7 Implementation
+
+Before you can get up and running with Slim you will need to choose a PSR-7 implementation that best fits your application. A few notable ones:
+- [Nyholm/psr7](https://github.com/Nyholm/psr7) - This is the fastest, strictest and most lightweight implementation at the moment
+- [Guzzle/psr7](https://github.com/guzzle/psr7) - This is the implementation used by the Guzzle Client. It is not as strict but adds some nice functionality for Streams and file handling. It is the second fastest implementation but is a bit bulkier
+- [zend-diactoros](https://github.com/zendframework/zend-diactoros) - This is the Zend implementation. It is the slowest implementation of the 3. 
+
+## Example Usage With Nyholm/psr7 and Nyholm/psr7-server
 
 Create an index.php file with the following contents:
 
 ```php
 <?php
+require 'vendor/autoload.php';
+
+use Nyholm\Psr7\Factory\Psr17Factory;
+use Nyholm\Psr7Server\ServerRequestCreator;
+use Slim\ResponseEmitter;
+
+$app = new Slim\App();
+$app->get('/hello/{name}', function ($request, $response, $args) {
+    return $response->getBody()->write("Hello, " . $args['name']);
+});
+
+$psr17Factory = new Psr17Factory();
+$request = ServerRequestCreator::fromGlobals();
+
+/**
+ * The App::run() Method takes 2 parameters
+ * In the case of Nyholm/psr7 the Psr17Factory provides all the Http-Factories in one class
+ * which include ResponseFactoryInterface
+ * @param ServerRequestInterface An instantiation of a ServerRequest
+ * @param ResponseFactoryInterface An instantiation of a ResponseFactory
+ */
+$response = $app->run($request, $psr17Factory);
+
+/**
+ * Once you have obtained the ResponseInterface from App::run()
+ * You will need to emit the response by using an emitter of your choice
+ * We will use Slim ResponseEmitter for this example
+ * But you could use Zend HttpHandleRunner SapiEmitter or other
+ */
+$responseEmitter = new ResponseEmitter();
+$responseEmitter->emit($response);
+```
+
+## Example Usage With Zend Diactoros & Zend HttpHandleRunner
 
+Create an index.php file with the following contents:
+
+```php
+<?php
 require 'vendor/autoload.php';
 
+use Zend\Diactoros\ResponseFactory;
+use Zend\Diactoros\ServerRequestFactory;
+use Zend\HttpHandlerRunner\Emitter\SapiEmitter;
+
 $app = new Slim\App();
+$app->get('/hello/{name}', function ($request, $response, $args) {
+    return $response->getBody()->write("Hello, " . $args['name']);
+});
 
+$responseFactory = new ResponseFactory();
+$serverRequestFactory = new ServerRequestFactory();
+$request = ServerRequestFactory::fromGlobals();
+
+/**
+ * The App::run() Method takes 2 parameters
+ * @param ServerRequestInterface An instantiation of a ServerRequest
+ * @param ResponseFactoryInterface An instantiation of a ResponseFactory
+ */
+$response = $app->run($request, $responseFactory);
+
+/**
+ * Once you have obtained the ResponseInterface from App::run()
+ * You will need to emit the response by using an emitter of your choice
+ * We will use Zend HttpHandleRunner SapiEmitter for this example
+ */
+$responseEmitter = new SapiEmitter();
+$responseEmitter->emit($response);
+```
+
+## Example Usage With Slim-Http Decorators, Zend Diactoros & Zend HttpHandleRunner
+```php
+<?php
+require 'vendor/autoload.php';
+
+use Slim\Http\Factory\DecoratedResponseFactory;
+use Slim\Http\Decorators\ServerRequestDecorator;
+use Zend\Diactoros\ResponseFactory;
+use Zend\Diactoros\ServerRequestFactory;
+use Zend\Diactoros\StreamFactory;
+use Zend\HttpHandlerRunner\Emitter\SapiEmitter;
+
+$app = new Slim\App();
+$app->get('/hello/{name}', function ($request, $response, $args) {
+    return $response->withJson(['Hello' => 'World']);
+});
+
+$responseFactory = new ResponseFactory();
+$streamFactory = new StreamFactory();
+$decoratedResponseFactory = new DecoratedResponseFactory($responseFactory, $streamFactory);
+
+$serverRequestFactory = new ServerRequestFactory();
+$request = ServerRequestFactory::fromGlobals();
+$decoratedServerRequest = new ServerRequestDecorator($request);
+
+/**
+ * The App::run() Method takes 2 parameters
+ * @param ServerRequestInterface An instantiation of a ServerRequest
+ * @param ResponseFactoryInterface An instantiation of a ResponseFactory
+ */
+$response = $app->run($decoratedRequest, $decoratedResponseFactory);
+
+/**
+ * Once you have obtained the ResponseInterface from App::run()
+ * You will need to emit the response by using an emitter of your choice
+ * We will use Zend HttpHandleRunner SapiEmitter for this example
+ */
+$responseEmitter = new SapiEmitter();
+$responseEmitter->emit($response);
+```
+
+## Example Usage With Guzzle PSR-7, Guzzle HTTP Factory
+
+Create an index.php file with the following contents:
+
+```php
+<?php
+require 'vendor/autoload.php';
+
+use GuzzleHttp\Psr7\ServerRequest;
+use Http\Factory\Guzzle\ResponseFactory;
+use Slim\ResponseEmitter;
+
+$app = new Slim\App();
 $app->get('/hello/{name}', function ($request, $response, $args) {
-    return $response->write("Hello, " . $args['name']);
+    return $response->getBody()->write("Hello, " . $args['name']);
 });
 
-$app->run();
+$responseFactory = new ResponseFactory();
+$request = ServerRequest::fromGlobals();
+
+/**
+ * The App::run() Method takes 2 parameters
+ * @param ServerRequestInterface An instantiation of a ServerRequest
+ * @param ResponseFactoryInterface An instantiation of a ResponseFactory
+ */
+$response = $app->run($request, $responseFactory);
+
+/**
+ * Once you have obtained the ResponseInterface from App::run()
+ * You will need to emit the response by using an emitter of your choice
+ * We will use Slim ResponseEmitter for this example
+ */
+$responseEmitter = new ResponseEmitter();
+$responseEmitter->emit($response);
 ```
 
 You may quickly test this using the built-in PHP server:
@@ -45,11 +187,12 @@ Going to http://localhost:8000/hello/world will now display "Hello, world".
 For more information on how to configure your web server, see the [Documentation](https://www.slimframework.com/docs/start/web-servers.html).
 
 ## Tests
-
-To execute the test suite, you'll need phpunit.
+To execute the test suite, you'll need to install all development dependencies.
 
 ```bash
-$ phpunit
+$ git clone https://github.com/slimphp/Slim-Http
+$ composer install
+$ composer test
 ```
 
 ## Contributing
@@ -75,6 +218,7 @@ If you discover security related issues, please email security@slimframework.com
 - [Josh Lockhart](https://github.com/codeguy)
 - [Andrew Smith](https://github.com/silentworks)
 - [Rob Allen](https://github.com/akrabat)
+- [Pierre Bérubé](https://github.com/l0gicgate)
 - [Gabriel Manricks](https://github.com/gmanricks)
 - [All Contributors](../../contributors)