├── .editorconfig ├── .gitignore ├── .travis.yml ├── LICENSE ├── README.md ├── composer.json ├── phpunit.xml.dist ├── src ├── Handler.php ├── HandlerProxy.php └── MiddlewareCollection.php └── tests ├── HandlerProxyTest.php ├── HandlerTest.php ├── MiddlewareCollectionTest.php └── TestCase.php /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig is awesome: http://EditorConfig.org 2 | 3 | # top-most EditorConfig file 4 | root = true 5 | 6 | # Unix-style newlines with a newline ending every file 7 | [*] 8 | end_of_line = lf 9 | insert_final_newline = true 10 | 11 | # PHP/JS Formatting 12 | [*.{php,js,json}] 13 | charset = utf-8 14 | trim_trailing_whitespace = true 15 | indent_style = space 16 | indent_size = 4 17 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | composer.phar 2 | composer.lock 3 | phpunit.xml 4 | vendor/ 5 | build/ 6 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: php 2 | 3 | php: 4 | - 7.0 5 | - 7.1 6 | - 7.2 7 | - nightly 8 | 9 | matrix: 10 | fast_finish: true 11 | allow_failures: 12 | - php: nightly 13 | include: 14 | - php: 7.0 15 | env: 'COMPOSER_FLAGS="--prefer-stable --prefer-lowest"' 16 | 17 | before_script: 18 | - travis_retry composer self-update 19 | - travis_retry composer update ${COMPOSER_FLAGS} --no-interaction --prefer-source 20 | 21 | script: 22 | - composer run test 23 | 24 | after_script: 25 | - bash -c '[[ -f "build/logs/clover.xml" ]] && wget https://scrutinizer-ci.com/ocular.phar' 26 | - bash -c '[[ -f "build/logs/clover.xml" ]] && php ocular.phar code-coverage:upload --format=php-clover build/logs/clover.xml' 27 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 Woody Gilk <@shadowhand> 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Equip Dispatch 2 | ============== 3 | 4 | [![Latest Stable Version](https://img.shields.io/packagist/v/equip/dispatch.svg)](https://packagist.org/packages/equip/dispatch) 5 | [![License](https://img.shields.io/packagist/l/equip/dispatch.svg)](https://github.com/equip/dispatch/blob/master/LICENSE) 6 | [![Build Status](https://travis-ci.org/equip/dispatch.svg)](https://travis-ci.org/equip/dispatch) 7 | [![Code Coverage](https://scrutinizer-ci.com/g/equip/dispatch/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/equip/dispatch/?branch=master) 8 | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/equip/dispatch/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/equip/dispatch/?branch=master) 9 | 10 | An HTTP Interop compatible middleware dispatcher in [Equip](http://equip.github.io/). 11 | Attempts to be [PSR-1](http://www.php-fig.org/psr/psr-1/), [PSR-2](http://www.php-fig.org/psr/psr-2/), 12 | [PSR-4](http://www.php-fig.org/psr/psr-4/), [PSR-7](http://www.php-fig.org/psr/psr-7/), 13 | and [PSR-15](http://www.php-fig.org/psr/psr-15/) compliant. 14 | 15 | Heavily influenced by the design of [Tari by ircmaxwell](https://github.com/ircmaxell/Tari-PHP). 16 | 17 | For more information, see [the documentation](http://equipframework.readthedocs.org/en/latest/dispatch). 18 | 19 | ## Install 20 | 21 | ``` 22 | composer require equip/dispatch 23 | ``` 24 | 25 | ## Usage 26 | 27 | The `MiddlewareCollection` is a container for middleware that acts as the entry point. 28 | It takes two arguments: 29 | 30 | - An array of `$middleware` which must be instances of server middleware. 31 | - A callable `$default` that acts as the terminator for the collection and returns 32 | an empty response. 33 | 34 | Once the collection is prepared it can dispatched with a server request and will return 35 | the response for output. 36 | 37 | ### Example 38 | 39 | ```php 40 | use Equip\Dispatch\MiddlewareCollection; 41 | 42 | // Any implementation of PSR-15 MiddlewareInterface 43 | $middleware = [ 44 | new FooMiddleware(), 45 | // ... 46 | ]; 47 | 48 | // Default handler for end of collection 49 | $default = function (ServerRequestInterface $request) { 50 | // Any implementation of PSR-7 ResponseInterface 51 | return new Response(); 52 | }; 53 | 54 | $collection = new MiddlewareCollection($middleware); 55 | 56 | // Any implementation of PSR-7 ServerRequestInterface 57 | $request = ServerRequest::fromGlobals(); 58 | $response = $collection->dispatch($request, $default); 59 | ``` 60 | 61 | ### Nested Collections 62 | 63 | The `MiddlewareCollection` also implements the `MiddlewareInterface` to allow 64 | collections to be nested: 65 | 66 | ```php 67 | use Equip\Dispatch\MiddlewareCollection; 68 | 69 | // Any implementation of PSR-15 MiddlewareInterface 70 | $middleware = [ 71 | new FooMiddleware(), 72 | 73 | // A nested collection 74 | new MiddlewareCollection(...), 75 | 76 | // More middleware 77 | new BarMiddleware(), 78 | // ... 79 | ]; 80 | 81 | $collection = new MiddlewareCollection($middleware); 82 | 83 | // HTTP factories can also be used 84 | $default = [$responseFactory, 'createResponse']; 85 | $request = $serverRequestFactory->createRequest($_SERVER); 86 | 87 | $response = $collection->dispatch($request, $default); 88 | ``` 89 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "equip/dispatch", 3 | "description": "An HTTP Interop compatible middleware dispatcher", 4 | "type": "library", 5 | "license": "MIT", 6 | "authors": [ 7 | { 8 | "name": "Equip Contributors", 9 | "homepage": "https://github.com/equip" 10 | } 11 | ], 12 | "require": { 13 | "php": ">=7.0", 14 | "psr/http-server-middleware": "^1.0" 15 | }, 16 | "require-dev": { 17 | "phpunit/phpunit": "^6.0", 18 | "eloquent/phony-phpunit": "^3.0", 19 | "eloquent/liberator": "^2.0" 20 | }, 21 | "autoload": { 22 | "psr-4": { 23 | "Equip\\Dispatch\\": "src/" 24 | } 25 | }, 26 | "autoload-dev": { 27 | "psr-4": { 28 | "Equip\\Dispatch\\": "tests/" 29 | } 30 | }, 31 | "scripts": { 32 | "test": "phpunit" 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /phpunit.xml.dist: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | ./tests 5 | 6 | 7 | 8 | 9 | ./src/ 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /src/Handler.php: -------------------------------------------------------------------------------- 1 | middleware = $middleware; 33 | $this->default = $default; 34 | } 35 | 36 | public function handle(ServerRequestInterface $request): ResponseInterface 37 | { 38 | if (empty($this->middleware[$this->index])) { 39 | return call_user_func($this->default, $request); 40 | } 41 | 42 | return $this->middleware[$this->index]->process($request, $this->nextHandler()); 43 | } 44 | 45 | /** 46 | * Get a handler pointing to the next middleware. 47 | * 48 | * @return static 49 | */ 50 | private function nextHandler() 51 | { 52 | $copy = clone $this; 53 | $copy->index++; 54 | 55 | return $copy; 56 | } 57 | } 58 | -------------------------------------------------------------------------------- /src/HandlerProxy.php: -------------------------------------------------------------------------------- 1 | adaptee = $adaptee; 22 | } 23 | 24 | /** 25 | * Process the request using a handler. 26 | * 27 | * @param ServerRequestInterface $request 28 | * 29 | * @return ResponseInterface 30 | */ 31 | public function __invoke(ServerRequestInterface $request) 32 | { 33 | return $this->adaptee->handle($request); 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /src/MiddlewareCollection.php: -------------------------------------------------------------------------------- 1 | middleware, $middleware); 47 | } 48 | 49 | /** 50 | * Add a middleware to the beginning of the stack. 51 | * 52 | * @param MiddlewareInterface $middleware 53 | * 54 | * @return void 55 | */ 56 | public function prepend(MiddlewareInterface $middleware) 57 | { 58 | array_unshift($this->middleware, $middleware); 59 | } 60 | 61 | /** 62 | * Dispatch the middleware stack. 63 | * 64 | * @param ServerRequestInterface $request 65 | * @param callable $default to call when no middleware is available 66 | * 67 | * @return ResponseInterface 68 | */ 69 | public function dispatch(ServerRequestInterface $request, callable $default) 70 | { 71 | $handler = new Handler($this->middleware, $default); 72 | 73 | return $handler->handle($request); 74 | } 75 | 76 | public function process(ServerRequestInterface $request, RequestHandlerInterface $nextContainerHandler): ResponseInterface 77 | { 78 | $default = new HandlerProxy($nextContainerHandler); 79 | $handler = new Handler($this->middleware, $default); 80 | 81 | return $handler->handle($request); 82 | } 83 | } 84 | -------------------------------------------------------------------------------- /tests/HandlerProxyTest.php: -------------------------------------------------------------------------------- 1 | mockRequest(); 14 | $response = $this->mockResponse(); 15 | 16 | $handler = Phony::mock(RequestHandlerInterface::class); 17 | 18 | $handler->handle->does(function (ServerRequestInterface $request) use ($response) { 19 | return $response; 20 | }); 21 | 22 | // Run 23 | $proxy = new HandlerProxy($handler->get()); 24 | $output = $proxy($request); 25 | 26 | // Verify 27 | Phony::inOrder( 28 | $handler->handle->calledWith($request) 29 | ); 30 | 31 | $this->assertTrue(is_callable($proxy)); 32 | $this->assertSame($response, $output); 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /tests/HandlerTest.php: -------------------------------------------------------------------------------- 1 | mockRequest(); 12 | $response = $this->mockResponse(); 13 | $default = $this->defaultReturnsResponse($response); 14 | 15 | // No middleware should only execute the default 16 | $middleware = []; 17 | 18 | // Run 19 | $handler = new Handler($middleware, $default); 20 | $output = $handler->handle($request); 21 | 22 | // Verify 23 | $this->assertSame($response, $output); 24 | } 25 | 26 | public function testPiping() 27 | { 28 | $request = $this->mockRequest(); 29 | $response = $this->mockResponse(); 30 | $default = $this->defaultReturnsResponse($response); 31 | 32 | $mocks = [ 33 | $this->mockMiddleware(), 34 | $this->mockMiddleware(), 35 | ]; 36 | 37 | $middleware = $this->realizeMocks($mocks); 38 | 39 | // Run 40 | $handler = new Handler($middleware, $default); 41 | $output = $handler->handle($request); 42 | 43 | // Verify 44 | Phony::inOrder( 45 | $mocks[0]->process->calledWith($request, '~'), 46 | $mocks[1]->process->calledWith($request, '~') 47 | ); 48 | 49 | $this->assertSame($output, $response); 50 | } 51 | } 52 | -------------------------------------------------------------------------------- /tests/MiddlewareCollectionTest.php: -------------------------------------------------------------------------------- 1 | assertInstanceOf(MiddlewareCollection::class, $collection); 15 | } 16 | 17 | public function testDefault() 18 | { 19 | $request = $this->mockRequest(); 20 | $response = $this->mockResponse(); 21 | $default = $this->defaultReturnsResponse($response); 22 | 23 | // No middleware should only execute the default 24 | $middleware = []; 25 | 26 | // Run 27 | $collection = new MiddlewareCollection($middleware); 28 | $output = $collection->dispatch($request, $default); 29 | 30 | // Verify 31 | $this->assertSame($response, $output); 32 | } 33 | 34 | public function testConstructorAppends() 35 | { 36 | $middleware = $this->realizeMocks([ 37 | $this->mockMiddleware(), 38 | $this->mockMiddleware(), 39 | ]); 40 | 41 | // Run 42 | $collection = new MiddlewareCollection($middleware); 43 | $accessibleCollection = Liberator::liberate($collection); 44 | 45 | // Verify 46 | $this->assertSame($middleware, $accessibleCollection->middleware); 47 | } 48 | 49 | public function testAppend() 50 | { 51 | list($first, $second) = $this->realizeMocks([ 52 | $this->mockMiddleware(), 53 | $this->mockMiddleware(), 54 | ]); 55 | 56 | // Run 57 | $collection = new MiddlewareCollection([$first]); 58 | $accessibleCollection = Liberator::liberate($collection); 59 | 60 | // Verify 61 | $this->assertSame([$first], $accessibleCollection->middleware); 62 | 63 | // Modify 64 | $collection->append($second); 65 | 66 | // Verify 67 | $this->assertSame([$first, $second], $accessibleCollection->middleware); 68 | } 69 | 70 | public function testPrepend() 71 | { 72 | list($first, $second) = $this->realizeMocks([ 73 | $this->mockMiddleware(), 74 | $this->mockMiddleware(), 75 | ]); 76 | 77 | // Run 78 | $collection = new MiddlewareCollection([$first]); 79 | $accessibleCollection = Liberator::liberate($collection); 80 | 81 | // Verify 82 | $this->assertSame([$first], $accessibleCollection->middleware); 83 | 84 | // Modify 85 | $collection->prepend($second); 86 | 87 | // Verify 88 | $this->assertSame([$second, $first], $accessibleCollection->middleware); 89 | } 90 | 91 | public function testDispatch() 92 | { 93 | $request = $this->mockRequest(); 94 | $response = $this->mockResponse(); 95 | $default = $this->defaultReturnsResponse($response); 96 | 97 | $mocks = [ 98 | $this->mockMiddleware(), 99 | $this->mockMiddleware(), 100 | $this->mockMiddleware(), 101 | ]; 102 | 103 | $middleware = $this->realizeMocks($mocks); 104 | 105 | // Run 106 | $collection = new MiddlewareCollection([ 107 | $middleware[0], 108 | // Collections can be nested 109 | new MiddlewareCollection([ 110 | $middleware[1], 111 | ]), 112 | $middleware[2], 113 | ]); 114 | 115 | $output = $collection->dispatch($request, $default); 116 | 117 | // Verify 118 | Phony::inOrder( 119 | $mocks[0]->process->calledWith($request, '~'), 120 | $mocks[1]->process->calledWith($request, '~'), 121 | $mocks[2]->process->calledWith($request, '~') 122 | ); 123 | 124 | $this->assertSame($response, $output); 125 | } 126 | } 127 | -------------------------------------------------------------------------------- /tests/TestCase.php: -------------------------------------------------------------------------------- 1 | get(); 20 | } 21 | 22 | /** 23 | * @return ResponseInterface 24 | */ 25 | protected function mockResponse() 26 | { 27 | return Phony::mock(ResponseInterface::class)->get(); 28 | } 29 | 30 | /** 31 | * Get a mock middleware. 32 | * 33 | * @return InstanceHandle 34 | */ 35 | protected function mockMiddleware() 36 | { 37 | $mock = Phony::mock(MiddlewareInterface::class); 38 | 39 | $mock->process->does(static function ($request, $handler) { 40 | return $handler->handle($request); 41 | }); 42 | 43 | return $mock; 44 | } 45 | 46 | /** 47 | * @param InstanceHandle[] $mocks 48 | * 49 | * @return object[] 50 | */ 51 | protected function realizeMocks(array $mocks) 52 | { 53 | return array_map(static function (InstanceHandle $mock) { 54 | return $mock->get(); 55 | }, $mocks); 56 | } 57 | 58 | /** 59 | * @param ResponseInterface $response 60 | * 61 | * @return callable 62 | */ 63 | protected function defaultReturnsResponse(ResponseInterface $response) 64 | { 65 | return function (ServerRequestInterface $request) use ($response) { 66 | return $response; 67 | }; 68 | } 69 | } 70 | --------------------------------------------------------------------------------