Add api documentation

.travis.yml

@@ -0,0 +1,30 @@
+language: php
+sudo: false
+
+php:
+  - 7.2
+
+cache:
+  directories:
+    - build/.composer-cache
+
+before_install:
+  - export COMPOSER_CACHE_DIR="$(pwd)/build/.composer-cache"
+  - export XDEBUG="/home/travis/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini"
+  - mv -v "$XDEBUG" "$XDEBUG.disabled"
+
+install:
+  - mkdir -p build/php_codesniffer build/php-cs-fixer build/ocular
+  - composer require --no-suggest --no-progress -n -a -d build/php-cs-fixer "friendsofphp/php-cs-fixer:^2.12"
+  - composer require --no-suggest --no-progress -n -a -d build/php_codesniffer "squizlabs/php_codesniffer:^3.3"
+  - composer require --no-suggest --no-progress -n -a -d build/ocular "scrutinizer/ocular:^1.5"
+  - composer update --no-suggest --no-progress -n -a
+
+script:
+  - build/php_codesniffer/vendor/bin/phpcs -p --standard=PSR2 src tests
+  - build/php-cs-fixer/vendor/bin/php-cs-fixer fix -v --dry-run --allow-risky=yes --using-cache=no
+  - mv -v "$XDEBUG.disabled" "$XDEBUG"
+  - vendor/bin/phpunit --coverage-clover=build/coverage.clover --coverage-text
+
+after_script:
+  - build/ocular/vendor/bin/ocular code-coverage:upload --format=php-clover build/coverage.clover

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## 0.1.0 - 2018-07-16
+### Added
+- Initial development release
+
+[Unreleased]: https://github.com/simply-framework/router/compare/v0.1.0...HEAD

LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2018 Riikka Kalliomäki
+
+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.

README.md

@@ -0,0 +1,24 @@
+# Middleware Application Framework
+
+This package provides a bare-bones middleware framework that implements the different PSR standards and
+takes advantage of the Simply Router and Container to create a coherent whole.
+
+The application framework takes advantage of the [PSR-7 HTTP Message Interface], [PSR-11 Container Interface]
+and [PSR-15 HTTP Handlers] while also looking into being compatible with upcoming [PSR-17 HTTP Factories] via
+the http-factory interop.
+
+NOTE: This package is part of a framework that is still highly experimental in nature. Stable api or proper
+documentation are not to be expected until the framework has been tested in practice.
+
+API documentation is available at: https://docs.riimu.net/simply/application/
+
+## Credits
+
+This library is Copyright (c) 2018 Riikka Kalliomäki.
+
+See LICENSE for license and copying information.
+
+[PSR-7 HTTP Message Interface]: https://www.php-fig.org/psr/psr-7
+[PSR-11 Container Interface]: https://www.php-fig.org/psr/psr-11
+[PSR-15 HTTP Handlers]: https://www.php-fig.org/psr/psr-15
+[PSR-17 HTTP Factories]: https://github.com/php-fig/fig-standards/tree/master/proposed/http-factory/

composer.json

@@ -23,8 +23,8 @@
     "psr/container": "^1.0",
     "psr/http-message": "^1.0",
     "http-interop/http-factory": "dev-master",
-    "simply/router": "^0.2.2",
-    "simply/container": "^0.1.0",
+    "simply/router": "^0.2.3",
+    "simply/container": "^0.2.0",
     "zendframework/zend-diactoros": "^1.8"
   },
   "require-dev": {

sami_config.php

@@ -0,0 +1,26 @@
+<?php
+
+use Sami\RemoteRepository\GitHubRemoteRepository;
+use Sami\Sami;
+use Symfony\Component\Finder\Finder;
+
+$iterator = Finder::create()
+    ->files()
+    ->name('*.php')
+    ->in(__DIR__ . '/src');
+
+$theme = getenv('SAMI_THEME');
+$settings = [];
+
+if ($theme) {
+    $settings['theme'] = basename($theme);
+    $settings['template_dirs'] = [dirname($theme)];
+}
+
+return new Sami($iterator, $settings + [
+    'title'                => 'Middleware Application Framework',
+    'build_dir'            => __DIR__ . '/build/doc',
+    'cache_dir'            => __DIR__ . '/build/cache',
+    'remote_repository'    => new GitHubRemoteRepository('simply-framework/application', __DIR__),
+    'default_opened_level' => 2,
+]);

src/Application.php

@@ -6,24 +6,38 @@
 use Simply\Application\HttpFactory\HttpFactoryInterface;
 
 /**
- * Application.
+ * The core application that runs the main middleware stack.
  * @author Riikka Kalliomäki <riikka.kalliomaki@gmail.com>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 class Application
 {
+    /** @var HttpFactoryInterface The factory used to generate the request from globals */
     private $httpFactory;
+
+    /** @var MiddlewareHandler The middleware stack that is run for every request */
     private $middlewareStack;
+
+    /** @var HttpClient The http client the application uses to communicate to the browser */
     private $httpClient;
 
+    /**
+     * Application constructor.
+     * @param HttpFactoryInterface $factory The factory used to generate the request from globals
+     * @param MiddlewareHandler $stack The middleware stack that is run for every request
+     * @param HttpClient $client The http client the application uses to communicate to the browser
+     */
     public function __construct(HttpFactoryInterface $factory, MiddlewareHandler $stack, HttpClient $client)
     {
         $this->httpFactory = $factory;
         $this->middlewareStack = $stack;
         $this->httpClient = $client;
     }
 
+    /**
+     * Runs the application middleware stack for the request and sends the response.
+     */
     public function run(): void
     {
         $request = $this->httpFactory->createServerRequestFromGlobals();

src/ApplicationProvider.php

@@ -14,7 +14,7 @@
 use Simply\Router\Router;
 
 /**
- * ApplicationProvider.
+ * Provides the default dependencies required by the application.
  * @author Riikka Kalliomäki <riikka.kalliomaki@gmail.com>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License

src/Handler/CallbackHandler.php

@@ -7,20 +7,26 @@
 use Psr\Http\Server\RequestHandlerInterface;
 
 /**
- * CallbackHandler.
+ * A handler that calls the given callback to generate the response.
  * @author Riikka Kalliomäki <riikka.kalliomaki@gmail.com>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 class CallbackHandler implements RequestHandlerInterface
 {
+    /** @var callable The callback to call with the request */
     private $callback;
 
+    /**
+     * CallbackHandler constructor.
+     * @param callable $callback The callback to call with the request
+     */
     public function __construct(callable $callback)
     {
         $this->callback = $callback;
     }
 
+    /** {@inheritdoc} */
     public function handle(ServerRequestInterface $request): ResponseInterface
     {
         return ($this->callback)($request);

src/Handler/ErrorHandler.php

@@ -8,20 +8,26 @@
 use Simply\Application\HttpFactory\HttpFactoryInterface;
 
 /**
- * ErrorHandler.
+ * A simple handler that sends a 500 error response.
  * @author Riikka Kalliomäki <riikka.kalliomaki@gmail.com>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 class ErrorHandler implements RequestHandlerInterface
 {
+    /** @var HttpFactoryInterface The http factory used to generate the response */
     private $httpFactory;
 
+    /**
+     * ErrorHandler constructor.
+     * @param HttpFactoryInterface $factory The http factory used to generate the response
+     */
     public function __construct(HttpFactoryInterface $factory)
     {
         $this->httpFactory = $factory;
     }
 
+    /** {@inheritdoc} */
     public function handle(ServerRequestInterface $request): ResponseInterface
     {
         return $this->httpFactory->createResponse(500, 'Internal Server Error')

src/Handler/MiddlewareHandler.php

@@ -8,36 +8,47 @@
 use Psr\Http\Server\RequestHandlerInterface;
 
 /**
- * MiddlewareStack.
+ * A middleware stack that acts like a request handler.
  * @author Riikka Kalliomäki <riikka.kalliomaki@gmail.com>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 class MiddlewareHandler implements RequestHandlerInterface
 {
-    /** @var MiddlewareInterface[] */
+    /** @var MiddlewareInterface[] List of middlewares to call */
     private $stack;
 
-    /** @var RequestHandlerInterface */
+    /** @var RequestHandlerInterface The fallback request handler */
     private $fallback;
 
+    /**
+     * MiddlewareHandler constructor.
+     * @param RequestHandlerInterface $fallback The fallback request handler to call
+     */
     public function __construct(RequestHandlerInterface $fallback)
     {
         $this->stack = [];
         $this->fallback = $fallback;
     }
 
-    public function push(MiddlewareInterface $middleware)
+    /**
+     * Adds a new middleware to the stack.
+     * @param MiddlewareInterface $middleware Additional middleware to add to the stack
+     */
+    public function push(MiddlewareInterface $middleware): void
     {
         $this->stack[] = $middleware;
     }
 
+    /** {@inheritdoc} */
     public function handle(Request $request): Response
     {
         $stack = $this->stack;
+
         $handler = new CallbackHandler(function (Request $request) use (& $stack, & $handler): Response {
-            if ($stack) {
-                $middleware = array_shift($stack);
+            $middleware = array_shift($stack);
+
+            if ($middleware instanceof MiddlewareInterface) {
                 return $middleware->process($request, $handler);
             }
 

src/Handler/NotFoundHandler.php

@@ -8,20 +8,26 @@
 use Simply\Application\HttpFactory\HttpFactoryInterface;
 
 /**
- * NotFoundHandler.
+ * A simple handler that sends a 404 response.
  * @author Riikka Kalliomäki <riikka.kalliomaki@gmail.com>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 class NotFoundHandler implements RequestHandlerInterface
 {
+    /** @var HttpFactoryInterface The factory used to generate the response */
     private $httpFactory;
 
+    /**
+     * NotFoundHandler constructor.
+     * @param HttpFactoryInterface $factory The factory use to generate the response
+     */
     public function __construct(HttpFactoryInterface $factory)
     {
         $this->httpFactory = $factory;
     }
 
+    /** {@inheritdoc} */
     public function handle(ServerRequestInterface $request): ResponseInterface
     {
         return $this->httpFactory->createResponse(404, 'Not Found')