From 5a8265f22b984e246e7e94e7d338352690c79f70 Mon Sep 17 00:00:00 2001 From: Rougin Gutib Date: Thu, 14 Dec 2023 00:39:46 +0800 Subject: [PATCH] Improve code documentation (#25) --- CHANGELOG.md | 81 +++---- ERRATUM.md | 41 +++- UPGRADE.md | 209 +++++++++++++++++- src/Application/Application.php | 7 +- src/Component/Collection.php | 32 +-- src/Component/Collector.php | 10 +- src/Component/ComponentInterface.php | 1 + src/ComponentCollection.php | 2 +- src/Components.php | 2 +- src/Container/AurynContainer.php | 12 +- src/Container/Container.php | 44 ++-- .../Exception/ContainerException.php | 7 +- src/Container/Exception/NotFoundException.php | 7 +- src/Container/LeagueContainer.php | 8 +- src/Container/Parameter.php | 3 +- src/Container/ReflectionContainer.php | 8 +- src/Container/VanillaContainer.php | 3 +- src/Debug/Debugger.php | 7 +- src/Debug/DebuggerInterface.php | 3 +- src/Debug/ErrorHandler.php | 11 +- src/Debug/ErrorHandlerIntegration.php | 14 +- src/Debug/ErrorHandlerInterface.php | 4 +- src/Debug/Vanilla/Debugger.php | 3 +- src/Debug/VanillaErrorHandler.php | 3 +- src/Debug/Whoops/Debugger.php | 5 +- src/Debug/WhoopsDebugger.php | 11 +- src/Debug/WhoopsErrorHandler.php | 19 +- src/Dispatching/BaseRouter.php | 7 +- src/Dispatching/Dispatcher.php | 7 +- src/Dispatching/DispatcherInterface.php | 5 +- src/Dispatching/FastRoute/Dispatcher.php | 9 +- src/Dispatching/FastRoute/Router.php | 9 +- src/Dispatching/Phroute/Dispatcher.php | 9 +- src/Dispatching/Phroute/Router.php | 9 +- src/Dispatching/Router.php | 7 +- src/Dispatching/RouterInterface.php | 5 +- src/Dispatching/Vanilla/Dispatcher.php | 7 +- src/Dispatching/Vanilla/Router.php | 7 +- src/Http/HttpIntegration.php | 15 +- src/Http/LICENSE.md | 2 +- src/Integration/Configuration.php | 4 +- src/Integration/ConfigurationIntegration.php | 7 +- src/Integration/ConfigurationInterface.php | 23 -- src/IoC/BaseContainer.php | 3 +- src/IoC/Container.php | 3 +- src/IoC/DependencyInjectorInterface.php | 15 ++ src/IoC/League/Container.php | 3 - src/IoC/LeagueContainer.php | 5 +- src/IoC/Vanilla/Container.php | 3 +- .../Vanilla/Exception/NotFoundException.php | 5 +- src/Middleware/Callback.php | 6 +- src/Middleware/Delegate.php | 3 +- src/Middleware/Dispatcher.php | 18 ++ src/Middleware/DispatcherInterface.php | 8 +- src/Middleware/Doublepass.php | 4 + src/Middleware/Handler.php | 11 +- src/Middleware/HandlerInterface.php | 2 + src/Middleware/Handlers/Handler030.php | 4 + src/Middleware/Handlers/Handler041.php | 4 + src/Middleware/Handlers/Handler050.php | 4 + src/Middleware/Handlers/Handler100.php | 4 + src/Middleware/Interop.php | 16 ++ src/Middleware/Middleware.php | 3 +- src/Middleware/MiddlewareInterface.php | 3 + src/Middleware/Stratigility/Middleware.php | 6 +- src/Middleware/StratigilityDispatcher.php | 22 +- src/Middleware/StratigilityMiddleware.php | 6 +- src/Middleware/Vanilla/Delegate.php | 8 +- src/Middleware/Vanilla/Middleware.php | 8 +- src/Middleware/VanillaDelegate.php | 7 +- src/Middleware/VanillaMiddleware.php | 5 +- src/Middleware/Version.php | 4 + src/Middleware/Wrapper.php | 4 +- src/Routing/DispatcherInterface.php | 2 +- src/Routing/FastRoute/Dispatcher.php | 3 - src/Routing/FastRoute/Router.php | 3 - src/Routing/FastRouteDispatcher.php | 6 +- src/Routing/FastRouteRouter.php | 20 +- src/Routing/Phroute/Dispatcher.php | 3 - src/Routing/Phroute/Router.php | 3 - src/Routing/PhrouteDispatcher.php | 26 ++- src/Routing/PhrouteResolver.php | 4 +- src/Routing/PhrouteRouter.php | 20 +- src/Routing/PhrouteWrapper.php | 6 +- src/Routing/Route.php | 50 +++-- src/Routing/RouteInterface.php | 18 +- src/Routing/Router.php | 8 +- src/Routing/RouterInterface.php | 2 +- src/Routing/RoutingIntegration.php | 44 ++-- src/Routing/Vanilla/Dispatcher.php | 5 +- src/Routing/Vanilla/Router.php | 5 +- src/System.php | 55 +++-- src/System/Endofline.php | 4 + src/System/Handler.php | 2 + src/System/Resolver.php | 4 + src/Template/RendererInterface.php | 2 +- src/Template/Twig.php | 6 +- src/Template/Twig/Renderer.php | 4 +- src/Template/TwigLoader.php | 6 +- src/Template/TwigRenderer.php | 4 +- src/Template/Vanilla/Renderer.php | 7 +- src/Template/VanillaRenderer.php | 5 +- tests/Application/ApplicationTestCases.php | 11 - tests/Debug/Vanilla/DebuggerTest.php | 26 ++- tests/Debug/Whoops/DebuggerTest.php | 52 +++-- tests/Routing/FastRouteDispatcherTest.php | 11 +- tests/Sample/Router.php | 4 +- 107 files changed, 844 insertions(+), 473 deletions(-) delete mode 100644 src/Integration/ConfigurationInterface.php create mode 100644 src/IoC/DependencyInjectorInterface.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 86a08eef..6ecb7c61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,10 @@ All notable changes to `Slytherin` will be documented in this file. - Backward compatibility for `LeagueContainer::set` (as of `~3.0`) - Backward compatibility for `TwigRenderer::render` (as of `~3.0`) - Backward compatibility for `StratigilityDispatcher::process` (until `~3.0`) -- Resolving type hinted routes for third-party routers +- Resolving type hinted routes for third-party routing dispatchers + +### Removed +- `Integration\ConfigurationInterface` as its not being used ## [0.9.6](https://github.com/rougin/slytherin/compare/v0.9.5...v0.9.6) - 2023-11-16 @@ -95,20 +98,15 @@ All notable changes to `Slytherin` will be documented in this file. ### Fixed - Retrieving a single uploaded file in `ServerRequest::getUploadedFiles` -## [0.9.0](https://github.com/rougin/slytherin/compare/v0.8.2...v0.9.0) - 2017-07-08 +## [0.9.0](https://github.com/rougin/slytherin/compare/v0.8.1...v0.9.0) - 2017-07-08 -**NOTE**: This release may break your application if upgrading from `v0.8.0` release. - -### Fixed -- Appending of middleware response from `DispatcherInterface`'s result in `Application::run` -- `Array to string conversion` error when add callback routes with arguments -- Compatibility issue for `Statigility\Middleware` -- Getting `$request` object in container after being defined in `Application::handle` +> [!CAUTION] +> This _may_ break your application if upgrading from `v0.8.0` release. ### Added -- Implementation of [PSR-7](http://www.php-fig.org/psr/psr-7), [PSR-11](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-11-container.md), and [PSR-15](https://github.com/php-fig/fig-standards/blob/master/proposed/http-middleware/middleware.md) standards. - - Packages `psr/container` and `psr/http-message` are already included in this release - - Install `http-interop/http-middleware` if you want to use middlewares in `Middleware` directory +- Implementation of PSR-07 (`psr/http-message`) +- Implementation of PSR-11 (from `container-interop/container-interop` to `psr/container`) +- Implementation of PSR-15 (`http-interop/http-middleware:0.4.1`) - Middlewares in `FastRoute\Dispatcher` and `Phroute\Dispatcher` - `Integration` for integrating third-party packages to Slytherin - `Configuration` for ease of access in getting configurations inside integrations @@ -143,21 +141,21 @@ All notable changes to `Slytherin` will be documented in this file. - `Template\Twig\Renderer` class - `Vanilla` related classes +### Fixed +- Appending of middleware response from `DispatcherInterface`'s result in `Application::run` +- `Array to string conversion` error when add callback routes with arguments +- Compatibility issue for `Statigility\Middleware` +- Getting `$request` object in container after being defined in `Application::handle` + ### Removed - HTTP method spoofing (apply it on a [middleware](https://github.com/rougin/weasley/blob/master/src/Http/Middleware/FormMethodSpoofing.php) instead) - Traits (in order to achieve PHP `v5.3.0` as the minimum required version) - `getEnvironment` and `setEnvironment` in `Debug\ErrorHandlerInterface` -## [0.8.2](https://github.com/rougin/slytherin/compare/v0.8.1...v0.8.2) - 2023-12-09 - -**NOTE**: This is a backport fix to lessen backward compatibility issues. - -### Fixed -- Compatibility issues from `v0.7.2` release - -## [0.8.1](https://github.com/rougin/slytherin/compare/v0.8.0...v0.8.1) - 2023-12-08 +## [0.8.1](https://github.com/rougin/slytherin/compare/v0.8.0...v0.8.1) - 2023-12-13 -**NOTE**: This is a backport fix to lessen backward compatibility issues. +> [!NOTE] +> This is a backport fix to lessen backward compatibility issues. ### Added - `alias` method in `AurynContainer` for backport fix from previous versions @@ -166,7 +164,7 @@ All notable changes to `Slytherin` will be documented in this file. - Compatibility issues from `v0.7.1` release - `html` as the default `$fileExtension` instead of `twig` -## [0.8.0](https://github.com/rougin/slytherin/compare/v0.7.2...v0.8.0) - 2016-09-08 +## [0.8.0](https://github.com/rougin/slytherin/compare/v0.7.1...v0.8.0) - 2016-09-08 ### Added - Implementation for [Phroute](https://github.com/mrjgreen/phroute) package @@ -180,7 +178,10 @@ All notable changes to `Slytherin` will be documented in this file. ### Removed - Third party packages in `require-dev` -## [0.7.2](https://github.com/rougin/slytherin/compare/v0.7.1...v0.7.2) - 2023-12-09 +## [0.7.1](https://github.com/rougin/slytherin/compare/v0.7.0...v0.7.1) - 2023-12-13 + +> [!NOTE] +> This is a backport fix to lessen backward compatibility issues. ### Added - `setTemplate` for setting `RendererInterface` in `Collection` @@ -189,15 +190,9 @@ All notable changes to `Slytherin` will be documented in this file. ### Changed - Rework `Collection`, `Collector` -### Fixed -- Add items in `Auryn\Container` - -## [0.7.1](https://github.com/rougin/slytherin/compare/v0.7.0...v0.7.1) - 2023-12-08 - -**NOTE**: This is a backport fix to lessen backward compatibility issues. - ### Fixed - Compatibility issues from `v0.6.1` release +- Add items in `Auryn\Container` ## [0.7.0](https://github.com/rougin/slytherin/compare/v0.6.1...v0.7.0) - 2016-07-17 @@ -214,9 +209,10 @@ All notable changes to `Slytherin` will be documented in this file. ### Removed - `HttpKernelInterface` -## [0.6.1](https://github.com/rougin/slytherin/compare/v0.6.0...v0.6.1) - 2023-12-08 +## [0.6.1](https://github.com/rougin/slytherin/compare/v0.6.0...v0.6.1) - 2023-12-13 -**NOTE**: This is a backport fix to lessen backward compatibility issues. +> [!NOTE] +> This is a backport fix to lessen backward compatibility issues. ### Fixed - Compatibility issues from `v0.5.1` release @@ -230,9 +226,10 @@ All notable changes to `Slytherin` will be documented in this file. ### Changed - File and directory structure -## [0.5.1](https://github.com/rougin/slytherin/compare/v0.5.0...v0.5.1) - 2023-12-08 +## [0.5.1](https://github.com/rougin/slytherin/compare/v0.5.0...v0.5.1) - 2023-12-13 -**NOTE**: This is a backport fix to lessen backward compatibility issues. +> [!NOTE] +> This is a backport fix to lessen backward compatibility issues. ### Added - `NoopFinalHandler` in `StratigilityMiddleware` @@ -253,9 +250,10 @@ All notable changes to `Slytherin` will be documented in this file. - PHP version to `v5.4.0` - Interface from `RequestInterface` to `ServerRequestInterface` in `Components` -## [0.4.4](https://github.com/rougin/slytherin/compare/v0.4.3...v0.4.4) - 2023-12-08 +## [0.4.4](https://github.com/rougin/slytherin/compare/v0.4.3...v0.4.4) - 2023-12-13 -**NOTE**: This is a backport fix to lessen backward compatibility issues. +> [!NOTE] +> This is a backport fix to lessen backward compatibility issues. ### Added - `ComponentCollection` @@ -290,7 +288,8 @@ All notable changes to `Slytherin` will be documented in this file. ## [0.4.0](https://github.com/rougin/slytherin/compare/v0.3.0...v0.4.0) - 2016-01-13 -**NOTE**: This release will break your application if upgrading from `v0.3.0` release. +> [!CAUTION] +> This _may_ break your application if upgrading from `v0.3.0` release. ### Added - `ComponentCollection::setContainer` for adding packages implemented on `Interop\Container\ContainerInterface` @@ -308,11 +307,12 @@ All notable changes to `Slytherin` will be documented in this file. - `Http` directory (will now require implementations in [PSR-7](http://www.php-fig.org/psr/psr-7)) - `DependencyInjectorInterface` (will now require implementations in `Interop\Container\ContainerInterface`) - `Http\ResponseInterface` dependency in `Dispatching\Dispatcher` -- Dependency of [nikic/fast-route](https://github.com/nikic/FastRoute) in `Dispatching` (use `Dispatching\FastRoute` instead) +- Dependency of `nikic/fast-route` in `Dispatching` (use `Dispatching\FastRoute` instead) ## [0.3.0](https://github.com/rougin/slytherin/compare/v0.2.2...v0.3.0) - 2015-11-02 -**NOTE**: This release will break your application if upgrading from `v0.2.0` release. +> [!CAUTION] +> This will break your application if upgrading from `v0.2.0` release. ### Added - Interface-based package implementations @@ -326,7 +326,8 @@ All notable changes to `Slytherin` will be documented in this file. ## [0.2.2](https://github.com/rougin/slytherin/compare/v0.2.1...v0.2.2) - 2023-12-08 -**NOTE**: This is a backport fix to lessen backward compatibility issues. +> [!NOTE] +> This is a backport fix to lessen backward compatibility issues. ### Changed - `post-install-cmd` to `post-update-cmd` in `README.md` diff --git a/ERRATUM.md b/ERRATUM.md index d6c09472..5b7607ec 100644 --- a/ERRATUM.md +++ b/ERRATUM.md @@ -4,7 +4,7 @@ The following are the erratum for each `README.md` found from the previous versi ## 0.9.0 -This version introduced a PSR-15 implementation based on `http-interop/http-middleware`. With this, kindly add the said package and update the packages using `composer update`: +This version introduced a support for PSR-15 implementations based on `http-interop/http-middleware`. With this, kindly add the said package and update the packages using `composer update`: ``` diff { @@ -174,6 +174,8 @@ class MiddlewarePackage extends AbstractComponent ``` ``` php +// src/Packages/TemplatePackage.php + namespace Rougin\Nostalgia\Packages; use Rougin\Slytherin\Component\AbstractComponent; @@ -403,6 +405,43 @@ In this version, the `patricklouys/http` has been removed in favor for PSR-07 (` } ``` +The version also favors the PSR-11 (`container-interop/container-interop`). The classes that implements `DependencyInjectorInterface` must be migrated to `ContainerInterface`: + +``` php +namespace Interop\Container; + +/** + * Describes the interface of a container that exposes methods to read its entries. + */ +interface ContainerInterface +{ + /** + * Finds an entry of the container by its identifier and returns it. + * + * @param string $id Identifier of the entry to look for. + * + * @throws NotFoundExceptionInterface No entry was found for **this** identifier. + * @throws ContainerExceptionInterface Error while retrieving the entry. + * + * @return mixed Entry. + */ + public function get($id); + + /** + * Returns true if the container can return an entry for the given identifier. + * Returns false otherwise. + * + * `has($id)` returning true does not mean that `get($id)` will not throw an exception. + * It does however mean that `get($id)` will not throw a `NotFoundExceptionInterface`. + * + * @param string $id Identifier of the entry to look for. + * + * @return bool + */ + public function has($id); +} +``` + Perform `composer update` afterwards to update the specified packages. ## 0.3.0 diff --git a/UPGRADE.md b/UPGRADE.md index c5fd9ff8..8c85ed8d 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -2,9 +2,140 @@ Below are the guides when upgrading from specified versions due to backward compatibility breaks: +> [!NOTE] +> There should be no backward compatibility issues if using the public methods of Slytherin components that are documented starting from `v0.3.0`. The following below should be considered if there are custom implementations that uses Slytherin's interfaces. + ## From `v0.8.0` to `v0.9.0` -No known backward compatibility issues found. +### Transition to the official PSR-11 implementation + +The `Container` has been reworked to support the official PSR-11 implementation (`psr/container`). The `ContainerInterface` was moved from `IoC` to `Container` directory. The `add` method was also changed to `set` to complement the `get` method from the official `ContainerInterface`: + +``` diff +-namespace Rougin\Slytherin\IoC; ++namespace Rougin\Slytherin\Container; + +-use Interop\Container\ContainerInterface as InteropContainerInterface; ++use Psr\Container\ContainerInterface as PsrContainerInterface; + +-interface ContainerInterface extends InteropContainerInterface ++interface ContainerInterface extends PsrContainerInterface + { + /** +- * @param string $id +- * @param mixed $concrete ++ * @param string $id ++ * @param mixed $concrete ++ * @return self + */ +- public function add($id, $concrete = null); ++ public function set($id, $concrete); + } +``` + +### Change of `DebuggerInterface` to `ErrorHandlerInterface` + +The `DebuggerInterface` is renamed to `ErrorHandlerInterface`. Although there is no backward compatibility break in this change, the specified interface removes required methods and may not be used in Slytherin: + +``` diff +namespace Rougin\Slytherin\Debug; + +-interface DebuggerInterface ++interface ErrorHandlerInterface + { +- /** +- * Sets up the environment to be used. +- * +- * @param string $environment +- * @return void +- */ +- public function setEnvironment($environment); +- +- /** +- * Returns the specified environment. +- * +- * @return string +- */ +- public function getEnvironment(); + + /** + * Registers the instance as a debugger. + * + * @return object + */ + public function display(); + } +``` + +### Transition to the official PSR-15 implementation + +The `Middleware` has been reworked due to the transition to the official PSR-15 implementation (`psr/http-server-middleware`). The `MiddlewareInterface` has been changed and it should be compatible with the various implementations of PSR-15: + +``` diff + namespace Rougin\Slytherin\Middleware; + +-use Psr\Http\Message\ResponseInterface as Response; +-use Psr\Http\Message\ServerRequestInterface as Request; ++use Psr\Http\Message\ServerRequestInterface; + + interface MiddlewareInterface + { + /** +- * @param \Psr\Http\Message\RequestInterface $request +- * @param \Psr\Http\Message\ResponseInterface $response +- * @param array $queue +- * @return \Psr\Http\Message\ResponseInterface|null ++ * @param \Psr\Http\Message\ServerRequestInterface $request ++ * @param \Rougin\Slytherin\Middleware\HandlerInterface $handler ++ * @return \Psr\Http\Message\ResponseInterface + */ +- public function __invoke(Request $request, Response $response, array $queue = []); ++ public function process(ServerRequestInterface $request, HandlerInterface $handler); + } +``` + +> [!NOTE] +> Although the `MiddlewareInterface` does not extend to the official `MiddlewareInterface`, Slytherin automatically converts the currently installed PSR-15 middleware (`http-interop/http-middleware` or `psr/http-server-middleware`) to its Slytherin counterpart. + +### Additional method for `DispatcherInterface` in `Routing` + +The `DispatcherInterface` for `Routing` has a new method named `setRouter`. If using the specified interface, kindly implement the recent method: + +``` diff + namespace Rougin\Slytherin\Routing; + + /** + * Dispatcher Interface + * + * An interface for handling third-party route dispatchers. + * + * @package Slytherin + * @author Rougin Gutib + */ + interface DispatcherInterface + { + /** + * Dispatches against the provided HTTP method verb and URI. + * + * @param string $method + * @param string $uri + * @return \Rougin\Slytherin\Routing\RouteInterface + * + * @throws \BadMethodCallException + */ + public function dispatch($method, $uri); + ++ /** ++ * Sets the router and parse its available routes if needed. ++ * ++ * @param \Rougin\Slytherin\Routing\RouterInterface $router ++ * @return self ++ * ++ * @throws \UnexpectedValueException ++ */ ++ public function setRouter(RouterInterface $router); + } +``` ## From `v0.7.0` to `v0.8.0` @@ -12,6 +143,8 @@ No known backward compatibility issues found. ## From `v0.6.0` to `v0.7.0` +### Upgrade version of `filp/whoops` + Although no backward compatibility issues found in Slytherin's code, one of the Slytherin's supported packages, `filp/whoops`, has an issue regarding PHP errors. With this, kindly change its version to `~2.0` in the `composer.json` then perform `composer update` after: ``` diff @@ -36,6 +169,8 @@ No known backward compatibility issues found. ## From `v0.3.0` to `v0.4.0` +### Transition to PSR-07 (HTTP messages) + The `v0.4.0` version requires a PSR-07 compliant package. See the `v0.4.0` in `ERRATUM` for updating the `composer.json`. With the transition to PSR-07, kindly update the following classes from `index.php`: @@ -55,22 +190,72 @@ With the transition to PSR-07, kindly update the following classes from `index.p // ... --// Initialize the RequestInterface and ResponseInterface ----------------------------- +// Initialize the RequestInterface and ResponseInterface ----------------------------- -$stream = file_get_contents('php://input'); -$request = new \Http\HttpRequest($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER, $stream); -$request = new Request($request); -$response = new Response(new \Http\HttpResponse); -+// Initialize the ServerRequestInterface and ResponseInterface --- +$request = ServerRequestFactory::fromGlobals(); +$response = new Response; $component->setHttp($request, $response); --// ----------------------------------------------------------------------------------- -+// --------------------------------------------------------------- +// ----------------------------------------------------------------------------------- // ... ``` -## From `v0.2.1` to `v0.3.0` +### Transition to PSR-11 (Containers) + +This version also introduced support for a PSR-11 compliant package. With this, the `DependencyInjectorInterface` has been removed and was replaced by `ContainerInterface` which extends to the `container-interop` package but added a new method: + +``` diff + namespace Rougin\Slytherin\IoC; + ++use Interop\Container\ContainerInterface as InteropContainerInterface; ++ +-interface DependencyInjectorInterface ++interface ContainerInterface extends InteropContainerInterface + { + /** +- * Instantiates/provisions a class instance. +- * +- * @param string $name +- * @param array $args +- * @return mixed ++ * Adds a new instance to the container. ++ * ++ * @param string $id ++ * @param mixed $concrete + */ +- public function make($name, array $args = array()); ++ public function add($id, $concrete = null); + } +``` + +### Change from `ErrorHandler` to `Debug` + +The `ErrorHandlerInterface` has been moved from `ErrorHandler` to `Debug` and renamed as `DebuggerInterface`. No backward compatibility break should occur as the latter interface extends to the former: + +``` diff +-namespace Rougin\Slytherin\ErrorHandler; ++namespace Rougin\Slytherin\Debug; + + /** +- * Error Handler Interface ++ * Debugger Interface + * +- * An interface for handling third party error handlers ++ * An interface for handling third party debuggers. + * + * @package Slytherin + * @author Rougin Royce Gutib + */ +-interface ErrorHandlerInterface ++interface DebuggerInterface +``` + +## From `v0.2.0` to `v0.3.0` + +### Migrating to a micro-framework package Due to transition from an application project to a micro-framework package, the following updates must be performed: @@ -108,7 +293,8 @@ Update the following details in `composer.json`: } ``` -**NOTE**: `Rougin\\Nostalgia\\` is only an example namespace. The said namespace can be changed for the whole project. +> [!NOTE] +> `Rougin\\Nostalgia\\` is only an example for the namespace. The `src` directory should have its own namespace for easy importing of its classes. Then execute `composer update` to update the packages: @@ -116,7 +302,7 @@ Then execute `composer update` to update the packages: $ composer update ``` -After updating, copy the `index.php` to `app/web` directory: +After updating the packages, copy the `index.php` to `app/web` directory: ``` diff +app/ @@ -125,7 +311,7 @@ After updating, copy the `index.php` to `app/web` directory: -index.php ``` -From the `index.php`, paste the following code: +Then copy the following code below to the said `index.php`: ``` php use Rougin\Slytherin\Application; @@ -298,4 +484,7 @@ If using the `Model` class for handling database results, replace it with the im + $st = $this->pdo->prepare($query); $st->execute(); -``` \ No newline at end of file +``` + +> [!NOTE] +> Use a third-party `PDO` implementation for improving code maintainability and readability. \ No newline at end of file diff --git a/src/Application/Application.php b/src/Application/Application.php index ddae47bc..5ba751de 100644 --- a/src/Application/Application.php +++ b/src/Application/Application.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Application; -use Rougin\Slytherin\Application as System; +use Rougin\Slytherin\Application as Slytherin; /** * Application * - * Integrates all specified components into the application. - * NOTE: To be removed in v1.0.0. Use \Application instead. + * NOTE: To be removed in v1.0.0. Use "\Application" instead. * * @package Slytherin * @author Rougin Gutib */ -class Application extends System +class Application extends Slytherin { } diff --git a/src/Component/Collection.php b/src/Component/Collection.php index 1ba81301..63a38076 100644 --- a/src/Component/Collection.php +++ b/src/Component/Collection.php @@ -15,7 +15,7 @@ /** * Component Collection * - * NOTE: To be removed in v1.0.0. Use "Integration" instead. + * Contains all the required components for Slytherin. * * @package Slytherin * @author Rougin Gutib @@ -38,7 +38,7 @@ public function __construct() } /** - * Adds a new instance to the container. + * Adds an instance to the container. * NOTE: To be removed in v1.0.0. Use "set" instead. * * @param string $id @@ -51,12 +51,10 @@ public function add($id, $concrete) } /** - * Finds an entry of the container by its identifier and returns it. + * Returns the specified component. * * @param string $id * @return object - * @throws \Psr\Container\NotFoundExceptionInterface - * @throws \Psr\Container\ContainerExceptionInterface */ public function get($id) { @@ -65,7 +63,7 @@ public function get($id) } /** - * Gets an instance of the container. + * Returns the container. * * @return \Rougin\Slytherin\Container\ContainerInterface */ @@ -75,7 +73,7 @@ public function getContainer() } /** - * Gets the debugger. + * Returns the debugger. * * @return \Rougin\Slytherin\Debug\ErrorHandlerInterface */ @@ -86,6 +84,7 @@ public function getDebugger() } /** + * Returns the dependency injector. * NOTE: To be removed in v1.0.0. Use "getContainer" instead. * * @return \Rougin\Slytherin\Container\ContainerInterface @@ -96,7 +95,7 @@ public function getDependencyInjector() } /** - * Gets the dispatcher. + * Returns the dispatcher. * * @return \Rougin\Slytherin\Dispatching\DispatcherInterface */ @@ -107,6 +106,7 @@ public function getDispatcher() } /** + * Returns the error handler. * NOTE: To be removed in v1.0.0. Use "getDebugger" instead. * * @return \Rougin\Slytherin\Debug\ErrorHandlerInterface @@ -117,7 +117,7 @@ public function getErrorHandler() } /** - * Gets the HTTP components. + * Returns the HTTP request and response. * * @return mixed */ @@ -127,7 +127,7 @@ public function getHttp() } /** - * Gets the request. + * Returns the HTTP request. * * @return \Psr\Http\Message\ServerRequestInterface */ @@ -138,7 +138,7 @@ public function getHttpRequest() } /** - * Gets the response. + * Returns the HTTP response. * * @return \Psr\Http\Message\ResponseInterface */ @@ -149,7 +149,7 @@ public function getHttpResponse() } /** - * Gets the middleware. + * Returns the middleware. * * @return \Rougin\Slytherin\Middleware\DispatcherInterface */ @@ -160,7 +160,7 @@ public function getMiddleware() } /** - * Gets the template. + * Returns the template. * * @return \Rougin\Slytherin\Template\RendererInterface */ @@ -171,7 +171,7 @@ public function getTemplate() } /** - * Returns true if the container can return an entry for the given identifier. + * Checks if a specified component exists. * * @param string $id * @return boolean @@ -182,7 +182,7 @@ public function has($id) } /** - * Sets a new instance to the container. + * Sets an instance to the collection. * * @param string $id * @param mixed $concrete @@ -220,6 +220,7 @@ public function setDebugger(ErrorHandlerInterface $debugger) } /** + * Sets the dependency injector. * NOTE: To be removed in v1.0.0. Use "setContainer" instead. * * @param \Rougin\Slytherin\Container\ContainerInterface $injector @@ -242,6 +243,7 @@ public function setDispatcher(Routing $dispatcher) } /** + * Sets the error handler. * NOTE: To be removed in v1.0.0. Use "setDebugger" instead. * * @param \Rougin\Slytherin\Debug\ErrorHandlerInterface $debugger diff --git a/src/Component/Collector.php b/src/Component/Collector.php index 92272b00..6496150d 100644 --- a/src/Component/Collector.php +++ b/src/Component/Collector.php @@ -38,7 +38,7 @@ public function __construct(array $items = array()) } /** - * Generates a Collection instance. + * Creates a new collection. * * @param \Rougin\Slytherin\Container\ContainerInterface $container * @return \Rougin\Slytherin\Component\Collection @@ -49,18 +49,18 @@ public function make(ContainerInterface $container) $collection->setContainer($container); - // If there is a defined container, set it first ----------- + // If there is a defined container, set it first ----------------- foreach ($this->items as $item) { if ($item->getType() === 'container') { - /** @var \Rougin\Slytherin\IoC\ContainerInterface */ + /** @var \Rougin\Slytherin\Container\ContainerInterface */ $result = $item->get(); $collection->setDependencyInjector($result); } } - // --------------------------------------------------------- + // --------------------------------------------------------------- foreach ($this->items as $item) { @@ -115,7 +115,7 @@ public function make(ContainerInterface $container) } /** - * Collects the specified components. + * Initializes the specified components. * * @param \Rougin\Slytherin\Component\ComponentInterface[]|string[] $components * @param \Rougin\Slytherin\IoC\ContainerInterface $container diff --git a/src/Component/ComponentInterface.php b/src/Component/ComponentInterface.php index 2e4a3541..b5a3f745 100644 --- a/src/Component/ComponentInterface.php +++ b/src/Component/ComponentInterface.php @@ -21,6 +21,7 @@ public function get(); /** * Returns the type of the component. + * Could be: container, dispatcher, debugger, http, middleware, template * * @return string */ diff --git a/src/ComponentCollection.php b/src/ComponentCollection.php index 861d5137..2fd92fe9 100644 --- a/src/ComponentCollection.php +++ b/src/ComponentCollection.php @@ -5,7 +5,7 @@ /** * Component Collection * - * NOTE: To be removed in v1.0.0. Use "Components" instead. + * NOTE: To be removed in v1.0.0. Use "Component\Collection" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Components.php b/src/Components.php index 55f9f19c..8d0d14ae 100644 --- a/src/Components.php +++ b/src/Components.php @@ -5,7 +5,7 @@ /** * Component Collection * - * NOTE: To be removed in v1.0.0. Use "Component\Collection" instead. + * NOTE: To be removed in v1.0.0. Use "ComponentCollection" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Container/AurynContainer.php b/src/Container/AurynContainer.php index 264519f2..7b5c88d3 100644 --- a/src/Container/AurynContainer.php +++ b/src/Container/AurynContainer.php @@ -10,12 +10,12 @@ * A simple implementation of a container that is built on top of * Daniel Lowrey's Auryn Inversion Of Control (IoC) Dependency Injector. * - * https://github.com/rdlowrey/auryn - * https://github.com/elazar/auryn-container-interop - * * @package Slytherin * @author Matthew Turland * @author Rougin Gutib + * + * @link https://github.com/rdlowrey/auryn + * @link https://github.com/elazar/auryn-container-interop */ class AurynContainer implements ContainerInterface { @@ -58,11 +58,11 @@ public function add($id, $concrete = null) /** * Finds an entry of the container by its identifier and returns it. * - * @throws \Psr\Container\NotFoundExceptionInterface - * @throws \Psr\Container\ContainerExceptionInterface - * * @param string $id * @return mixed + * + * @throws \Psr\Container\NotFoundExceptionInterface + * @throws \Psr\Container\ContainerExceptionInterface */ public function get($id) { diff --git a/src/Container/Container.php b/src/Container/Container.php index f1c9fd49..7449c3ff 100644 --- a/src/Container/Container.php +++ b/src/Container/Container.php @@ -3,14 +3,12 @@ namespace Rougin\Slytherin\Container; use Psr\Container\ContainerInterface as PsrContainerInterface; -use Psr\Container\NotFoundExceptionInterface; -use Psr\Http\Message\ServerRequestInterface; use Rougin\Slytherin\System\Resolver; /** * Container * - * A simple container that is implemented on \Psr\Container\ContainerInterface. + * A simple container that is implemented on PSR-11. * * @package Slytherin * @author Rougin Gutib @@ -23,28 +21,26 @@ class Container implements ContainerInterface protected $extra; /** - * NOTE: To be removed in v1.0.0. Use "protected" visibility instead. - * - * @var array + * @var array */ - public $instances = array(); + protected $items = array(); /** * Initializes the container instance. * - * @param array $instances - * @param \Psr\Container\ContainerInterface|null $container + * @param array $items + * @param \Psr\Container\ContainerInterface|null $extra */ - public function __construct(array $instances = array(), PsrContainerInterface $container = null) + public function __construct(array $items = array(), PsrContainerInterface $extra = null) { - $this->instances = $instances; + $this->items = $items; - if (! $container) + if (! $extra) { - $container = new ReflectionContainer; + $extra = new ReflectionContainer; } - $this->extra = $container; + $this->extra = $extra; } /** @@ -52,7 +48,7 @@ public function __construct(array $instances = array(), PsrContainerInterface $c * NOTE: To be removed in v1.0.0. Use "set" instead. * * @param string $id - * @param object $concrete + * @param mixed $concrete * @return self */ public function add($id, $concrete) @@ -69,7 +65,7 @@ public function add($id, $concrete) */ public function alias($id, $original) { - $this->instances[$id] = $this->get($original); + $this->items[$id] = $this->get($original); return $this; } @@ -77,11 +73,11 @@ public function alias($id, $original) /** * Finds an entry of the container by its identifier and returns it. * + * @param string $id + * @return mixed + * * @throws \Psr\Container\NotFoundExceptionInterface * @throws \Psr\Container\ContainerExceptionInterface - * - * @param string $id - * @return object */ public function get($id) { @@ -92,9 +88,9 @@ public function get($id) throw new Exception\NotFoundException(sprintf($message, $id)); } - if (isset($this->instances[$id])) + if (isset($this->items[$id])) { - $entry = $this->instances[$id]; + $entry = $this->items[$id]; } else { @@ -118,19 +114,19 @@ public function get($id) */ public function has($id) { - return isset($this->instances[$id]) || $this->extra->has($id); + return isset($this->items[$id]) || $this->extra->has($id); } /** * Sets a new instance to the container. * * @param string $id - * @param object $concrete + * @param mixed $concrete * @return self */ public function set($id, $concrete) { - $this->instances[$id] = $concrete; + $this->items[$id] = $concrete; return $this; } diff --git a/src/Container/Exception/ContainerException.php b/src/Container/Exception/ContainerException.php index 6a1d01f8..7b557b60 100644 --- a/src/Container/Exception/ContainerException.php +++ b/src/Container/Exception/ContainerException.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Container\Exception; -use Rougin\Slytherin\Container\ContainerException as BaseException; +use Rougin\Slytherin\Container\ContainerException as Slytherin; /** * Container Exception * - * A specified exception in handling errors in containers. - * NOTE: To be removed in v1.0.0. Use Container\ContainerException instead. + * NOTE: To be removed in v1.0.0. Use "Container\ContainerException" instead. * * @package Slytherin * @author Rougin Gutib */ -class ContainerException extends BaseException +class ContainerException extends Slytherin { } diff --git a/src/Container/Exception/NotFoundException.php b/src/Container/Exception/NotFoundException.php index 5470a2e1..f316d48e 100644 --- a/src/Container/Exception/NotFoundException.php +++ b/src/Container/Exception/NotFoundException.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Container\Exception; -use Rougin\Slytherin\Container\NotFoundException as BaseException; +use Rougin\Slytherin\Container\NotFoundException as Slytherin; /** * Not Found Exception * - * A specified exception in handling errors in containers. - * NOTE: To be removed in v1.0.0. Use Container\NotFoundException instead. + * NOTE: To be removed in v1.0.0. Use "Container\NotFoundException" instead. * * @package Slytherin * @author Rougin Gutib */ -class NotFoundException extends BaseException +class NotFoundException extends Slytherin { } diff --git a/src/Container/LeagueContainer.php b/src/Container/LeagueContainer.php index 45634926..0701ab5c 100644 --- a/src/Container/LeagueContainer.php +++ b/src/Container/LeagueContainer.php @@ -2,19 +2,19 @@ namespace Rougin\Slytherin\Container; -use League\Container\Container as BaseContainer; +use League\Container\Container as League; /** * League Container * * A simple implementation of a container that is based on League\Container. * - * http://container.thephpleague.com - * * @package Slytherin * @author Rougin Gutib + * + * @link http://container.thephpleague.com */ -class LeagueContainer extends BaseContainer implements ContainerInterface +class LeagueContainer extends League implements ContainerInterface { /** * Sets a new instance to the container. diff --git a/src/Container/Parameter.php b/src/Container/Parameter.php index bfe52a67..13fa6b25 100644 --- a/src/Container/Parameter.php +++ b/src/Container/Parameter.php @@ -6,7 +6,6 @@ * Parameter * * A backward compatible class for handling ReflectionParameter. - * NOTE: This will only work on PHP <= 8.0. Needs to be refactored. * * @package Slytherin * @author Rougin Gutib @@ -29,7 +28,7 @@ public function __construct(\ReflectionParameter $param) } /** - * Gets a \ReflectionClass object for the parameter being reflected or "null". + * Returns a \ReflectionClass object for the parameter being reflected or "null". * * @return \ReflectionClass|null * @codeCoverageIgnore diff --git a/src/Container/ReflectionContainer.php b/src/Container/ReflectionContainer.php index 54c5a4e8..e1cec447 100644 --- a/src/Container/ReflectionContainer.php +++ b/src/Container/ReflectionContainer.php @@ -15,15 +15,15 @@ class ReflectionContainer implements PsrContainerInterface { /** - * @link https://petersuhm.com/recursively-resolving-dependencies-with-phps-reflection-api-part-1 - * * Finds an entry of the container by its identifier and returns it. * + * @param string $id + * @return mixed + * * @throws \Psr\Container\NotFoundExceptionInterface * @throws \Psr\Container\ContainerExceptionInterface * - * @param string $id - * @return mixed + * @link https://petersuhm.com/recursively-resolving-dependencies-with-phps-reflection-api-part-1 */ public function get($id) { diff --git a/src/Container/VanillaContainer.php b/src/Container/VanillaContainer.php index b24e14e6..ede371e8 100644 --- a/src/Container/VanillaContainer.php +++ b/src/Container/VanillaContainer.php @@ -5,8 +5,7 @@ /** * Container * - * A simple container that is implemented on \Psr\Container\ContainerInterface. - * NOTE: To be removed in v1.0.0. Use "Container\Container" instead. + * NOTE: To be removed in v1.0.0. Use "Container" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Debug/Debugger.php b/src/Debug/Debugger.php index ed2686c5..821c6ede 100644 --- a/src/Debug/Debugger.php +++ b/src/Debug/Debugger.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Debug; -use Rougin\Slytherin\Debug\Vanilla\Debugger as BaseDebugger; +use Rougin\Slytherin\Debug\Vanilla\Debugger as Slytherin; /** * Debugger * - * A simple implementation of a debugger. - * NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. + * NOTE: To be removed in v1.0.0. Use "VanillaDebugger" instead. * * @package Slytherin * @author Rougin Gutib */ -class Debugger extends BaseDebugger +class Debugger extends Slytherin { } diff --git a/src/Debug/DebuggerInterface.php b/src/Debug/DebuggerInterface.php index 89ee7adf..a632cdeb 100644 --- a/src/Debug/DebuggerInterface.php +++ b/src/Debug/DebuggerInterface.php @@ -5,8 +5,7 @@ /** * Debugger Interface * - * An interface for handling third party debuggers. - * NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. + * NOTE: To be removed in v1.0.0. Use "ErrorHandlerInterface" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Debug/ErrorHandler.php b/src/Debug/ErrorHandler.php index 77150f63..3907046e 100644 --- a/src/Debug/ErrorHandler.php +++ b/src/Debug/ErrorHandler.php @@ -5,8 +5,7 @@ /** * Error Handler * - * A simple implementation of a debugger. - * NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. + * A simple implementation of an error handler. * * @package Slytherin * @author Rougin Gutib @@ -28,7 +27,7 @@ public function __construct($environment = 'development') /** * Sets up the environment to be used. - * NOTE: To be removed in v1.0.0. + * NOTE: To be removed in v1.0.0. It is not part of the "ErrorHandlerInterface". * * @param string $environment * @return self @@ -41,8 +40,8 @@ public function setEnvironment($environment) } /** - * Gets the specified environment. - * NOTE: To be removed in v1.0.0. + * Returns the specified environment. + * NOTE: To be removed in v1.0.0. It is not part of the "ErrorHandlerInterface". * * @return string */ @@ -54,7 +53,7 @@ public function getEnvironment() /** * Registers the instance as an error handler. * - * @return mixed + * @return void */ public function display() { diff --git a/src/Debug/ErrorHandlerIntegration.php b/src/Debug/ErrorHandlerIntegration.php index 812534ce..6ac43052 100644 --- a/src/Debug/ErrorHandlerIntegration.php +++ b/src/Debug/ErrorHandlerIntegration.php @@ -2,16 +2,15 @@ namespace Rougin\Slytherin\Debug; -use Rougin\Slytherin\Application; use Rougin\Slytherin\Container\ContainerInterface; use Rougin\Slytherin\Integration\Configuration; use Rougin\Slytherin\Integration\IntegrationInterface; +use Rougin\Slytherin\System; /** * Error Handler Integration * * An integration for defined error handlers to be included in Slytherin. - * NOTE: To be removed in v1.0.0. Move to "Integration" directory instead. * * @package Slytherin * @author Rougin Gutib @@ -30,6 +29,8 @@ public function define(ContainerInterface $container, Configuration $config) /** @var string */ $environment = $config->get('app.environment', 'development'); + if ($environment !== 'development') return $container; + $handler = new ErrorHandler($environment); if (interface_exists('Whoops\RunInterface')) @@ -39,13 +40,6 @@ public function define(ContainerInterface $container, Configuration $config) $handler = new WhoopsErrorHandler($whoops, $environment); } - if ($environment === 'development') - { - ini_set('display_errors', '1'); - - error_reporting(E_ALL); $handler->display(); - } - - return $container; + return $container->set(System::DEBUGGER, $handler); } } diff --git a/src/Debug/ErrorHandlerInterface.php b/src/Debug/ErrorHandlerInterface.php index d0ae3934..ff83a69b 100644 --- a/src/Debug/ErrorHandlerInterface.php +++ b/src/Debug/ErrorHandlerInterface.php @@ -5,7 +5,7 @@ /** * Error Handler Interface * - * An interface for handling third party error handlers. + * An interface for handling third-party error handlers. * * @package Slytherin * @author Rougin Gutib @@ -15,7 +15,7 @@ interface ErrorHandlerInterface /** * Registers the instance as an error handler. * - * @return object + * @return void */ public function display(); } diff --git a/src/Debug/Vanilla/Debugger.php b/src/Debug/Vanilla/Debugger.php index 40e80445..211a3b1a 100644 --- a/src/Debug/Vanilla/Debugger.php +++ b/src/Debug/Vanilla/Debugger.php @@ -7,8 +7,7 @@ /** * Debugger * - * A simple implementation of a debugger. - * NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. + * NOTE: To be removed in v1.0.0. Use "VanillaErrorHandler" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Debug/VanillaErrorHandler.php b/src/Debug/VanillaErrorHandler.php index 0062de5a..a3114b02 100644 --- a/src/Debug/VanillaErrorHandler.php +++ b/src/Debug/VanillaErrorHandler.php @@ -5,8 +5,7 @@ /** * Error Handler * - * A simple implementation of a debugger. - * NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. + * NOTE: To be removed in v1.0.0. Use "ErrorHandler" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Debug/Whoops/Debugger.php b/src/Debug/Whoops/Debugger.php index 7d40c3a3..e4a818dc 100644 --- a/src/Debug/Whoops/Debugger.php +++ b/src/Debug/Whoops/Debugger.php @@ -7,10 +7,7 @@ /** * Debugger * - * A simple implementation of a debugger built on top of Filipe Dobreira's - * Whoops. NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. - * - * http://filp.github.io/whoops + * NOTE: To be removed in v1.0.0. Use "WhoopsErrorHandler" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Debug/WhoopsDebugger.php b/src/Debug/WhoopsDebugger.php index 8fafa465..95bd9830 100644 --- a/src/Debug/WhoopsDebugger.php +++ b/src/Debug/WhoopsDebugger.php @@ -2,19 +2,16 @@ namespace Rougin\Slytherin\Debug; -use Rougin\Slytherin\Debug\Whoops\Debugger as BaseDebugger; +use Rougin\Slytherin\Debug\Whoops\Debugger as Slytherin; /** - * Debugger + * Whoops Debugger * - * A simple implementation of a debugger built on top of Filipe Dobreira's - * Whoops. NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. - * - * http://filp.github.io/whoops + * NOTE: To be removed in v1.0.0. Use "Whoops\Debugger" instead. * * @package Slytherin * @author Rougin Gutib */ -class WhoopsDebugger extends BaseDebugger +class WhoopsDebugger extends Slytherin { } diff --git a/src/Debug/WhoopsErrorHandler.php b/src/Debug/WhoopsErrorHandler.php index da78781d..c5f901e1 100644 --- a/src/Debug/WhoopsErrorHandler.php +++ b/src/Debug/WhoopsErrorHandler.php @@ -8,13 +8,12 @@ /** * Whoops Error Handler * - * A simple implementation of an error handler built on top of Filipe Dobreira's - * Whoops. NOTE: To be removed in v1.0.0. Use "ErrorHandlerIntegration" instead. - * - * http://filp.github.io/whoops + * A simple implementation of an error handler built on top of Whoops. * * @package Slytherin * @author Rougin Gutib + * + * @link http://filp.github.io/whoops */ class WhoopsErrorHandler implements ErrorHandlerInterface { @@ -41,7 +40,7 @@ public function __construct(Run $whoops, $environment = 'development') /** * Sets up the environment to be used. - * NOTE: To be removed in v1.0.0. + * NOTE: To be removed in v1.0.0. It is not part of the "ErrorHandlerInterface". * * @param string $environment * @return self @@ -54,8 +53,8 @@ public function setEnvironment($environment) } /** - * Gets the specified environment. - * NOTE: To be removed in v1.0.0. + * Returns the specified environment. + * NOTE: To be removed in v1.0.0. It is not part of the "ErrorHandlerInterface". * * @return string */ @@ -66,7 +65,7 @@ public function getEnvironment() /** * Returns a listing of handlers. - * NOTE: To be removed in v1.0.0. Use __call" instead. + * NOTE: To be removed in v1.0.0. Use the magic method "__call" instead. * * @return \Whoops\Handler\HandlerInterface[] */ @@ -78,7 +77,7 @@ public function getHandlers() /** * Registers the instance as an error handler. * - * @return mixed + * @return void */ public function display() { @@ -88,7 +87,7 @@ public function display() $this->__call('pushHandler', array($handler)); - return $this->whoops->register(); + $this->whoops->register(); } /** diff --git a/src/Dispatching/BaseRouter.php b/src/Dispatching/BaseRouter.php index d416ffa5..d9abeb1d 100644 --- a/src/Dispatching/BaseRouter.php +++ b/src/Dispatching/BaseRouter.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Dispatching; -use Rougin\Slytherin\Routing\Router as AbstractRouter; +use Rougin\Slytherin\Routing\Router as Slytherin; /** * Base Router * - * A simple implementation of a router that is based on RouterInterface. - * NOTE: To be removed in v1.0.0 + * NOTE: To be removed in v1.0.0. Use "Routing\Router" instead. * * @package Slytherin * @author Rougin Gutib */ -abstract class BaseRouter extends AbstractRouter +abstract class BaseRouter extends Slytherin { } diff --git a/src/Dispatching/Dispatcher.php b/src/Dispatching/Dispatcher.php index dde3c9e1..7eb09915 100644 --- a/src/Dispatching/Dispatcher.php +++ b/src/Dispatching/Dispatcher.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Dispatching; -use Rougin\Slytherin\Dispatching\Vanilla\Dispatcher as BaseDispatcher; +use Rougin\Slytherin\Dispatching\Vanilla\Dispatcher as Slytherin; /** * Dispatcher * - * A simple implementation of a route dispatcher that is based on DispatcherInterface. - * NOTE: To be removed in v1.0.0. Use "Routing\Dispatcher" instead. + * NOTE: To be removed in v1.0.0. Use "Vanilla\Dispatcher" instead. * * @package Slytherin * @author Rougin Gutib */ -class Dispatcher extends BaseDispatcher +class Dispatcher extends Slytherin { } diff --git a/src/Dispatching/DispatcherInterface.php b/src/Dispatching/DispatcherInterface.php index 3e58aed3..ba7bded3 100644 --- a/src/Dispatching/DispatcherInterface.php +++ b/src/Dispatching/DispatcherInterface.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Dispatching; -use Rougin\Slytherin\Routing\DispatcherInterface as BaseDispatcher; +use Rougin\Slytherin\Routing\DispatcherInterface as Slytherin; /** * Dispatcher Interface * - * An interface for handling third party route dispatchers. * NOTE: To be removed in v1.0.0. Use "Routing\DispatcherInterface" instead. * * @package Slytherin * @author Rougin Gutib */ -interface DispatcherInterface extends BaseDispatcher +interface DispatcherInterface extends Slytherin { } diff --git a/src/Dispatching/FastRoute/Dispatcher.php b/src/Dispatching/FastRoute/Dispatcher.php index a73fad7b..5dce7faa 100644 --- a/src/Dispatching/FastRoute/Dispatcher.php +++ b/src/Dispatching/FastRoute/Dispatcher.php @@ -2,19 +2,16 @@ namespace Rougin\Slytherin\Dispatching\FastRoute; -use Rougin\Slytherin\Routing\FastRoute\Dispatcher as BaseDispatcher; +use Rougin\Slytherin\Routing\FastRoute\Dispatcher as Slytherin; /** * FastRoute Dispatcher * - * A simple implementation of dispatcher that is built on top of FastRoute. - * NOTE: To be removed in v1.0.0. Use "Routing\FastRouteDispatcher" instead. - * - * https://github.com/nikic/FastRoute + * NOTE: To be removed in v1.0.0. Use "Routing\FastRoute\Dispatcher" instead. * * @package Slytherin * @author Rougin Gutib */ -class Dispatcher extends BaseDispatcher +class Dispatcher extends Slytherin { } diff --git a/src/Dispatching/FastRoute/Router.php b/src/Dispatching/FastRoute/Router.php index 00298057..b6ef7074 100644 --- a/src/Dispatching/FastRoute/Router.php +++ b/src/Dispatching/FastRoute/Router.php @@ -2,19 +2,16 @@ namespace Rougin\Slytherin\Dispatching\FastRoute; -use Rougin\Slytherin\Routing\FastRoute\Router as BaseRouter; +use Rougin\Slytherin\Routing\FastRoute\Router as Slytherin; /** * FastRoute Router * - * A simple implementation of router that is built on top of FastRoute. - * NOTE: To be removed in v1.0.0. Use "Routing\FastRouteRouter" instead. - * - * https://github.com/nikic/FastRoute + * NOTE: To be removed in v1.0.0. Use "Routing\FastRoute\Router" instead. * * @package Slytherin * @author Rougin Gutib */ -class Router extends BaseRouter +class Router extends Slytherin { } diff --git a/src/Dispatching/Phroute/Dispatcher.php b/src/Dispatching/Phroute/Dispatcher.php index dca01614..1b15f81f 100644 --- a/src/Dispatching/Phroute/Dispatcher.php +++ b/src/Dispatching/Phroute/Dispatcher.php @@ -2,19 +2,16 @@ namespace Rougin\Slytherin\Dispatching\Phroute; -use Rougin\Slytherin\Routing\Phroute\Dispatcher as BaseDispatcher; +use Rougin\Slytherin\Routing\Phroute\Dispatcher as Slytherin; /** * Phroute Dispatcher * - * A simple implementation of dispatcher that is built on top of Phroute. - * NOTE: To be removed in v1.0.0. Use "Routing\PhrouteDispatcher" instead. - * - * https://github.com/mrjgreen/phroute + * NOTE: To be removed in v1.0.0. Use "Routing\Phroute\Dispatcher" instead. * * @package Slytherin * @author Rougin Gutib */ -class Dispatcher extends BaseDispatcher +class Dispatcher extends Slytherin { } diff --git a/src/Dispatching/Phroute/Router.php b/src/Dispatching/Phroute/Router.php index c8771327..08d23dfb 100644 --- a/src/Dispatching/Phroute/Router.php +++ b/src/Dispatching/Phroute/Router.php @@ -2,19 +2,16 @@ namespace Rougin\Slytherin\Dispatching\Phroute; -use Rougin\Slytherin\Routing\Phroute\Router as BaseRouter; +use Rougin\Slytherin\Routing\Phroute\Router as Slytherin; /** * Phroute Router * - * A simple implementation of router that is built on top of Phroute. - * NOTE: To be removed in v1.0.0. Use "Routing\PhrouteRouter" instead. - * - * https://github.com/mrjgreen/phroute + * NOTE: To be removed in v1.0.0. Use "Routing\Phroute\Router" instead. * * @package Slytherin * @author Rougin Gutib */ -class Router extends BaseRouter +class Router extends Slytherin { } diff --git a/src/Dispatching/Router.php b/src/Dispatching/Router.php index ff79ca81..f17fc3b0 100644 --- a/src/Dispatching/Router.php +++ b/src/Dispatching/Router.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Dispatching; -use Rougin\Slytherin\Dispatching\Vanilla\Router as VanillaRouter; +use Rougin\Slytherin\Dispatching\Vanilla\Router as Slytherin; /** * Dispatcher * - * A simple implementation of a router that is based on RouterInterface. - * NOTE: To be removed in v1.0.0. Use "Routing\Router" instead. + * NOTE: To be removed in v1.0.0. Use "Vanilla\Router" instead. * * @package Slytherin * @author Rougin Gutib */ -class Router extends VanillaRouter +class Router extends Slytherin { } diff --git a/src/Dispatching/RouterInterface.php b/src/Dispatching/RouterInterface.php index a9031431..dadde08b 100644 --- a/src/Dispatching/RouterInterface.php +++ b/src/Dispatching/RouterInterface.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Dispatching; -use Rougin\Slytherin\Routing\RouterInterface as AbstractRouter; +use Rougin\Slytherin\Routing\RouterInterface as Slytherin; /** * Router Interface * - * An interface for handling third party routers. * NOTE: To be removed in v1.0.0. Use "Routing\RouterInterface" instead. * * @package Slytherin * @author Rougin Gutib */ -interface RouterInterface extends AbstractRouter +interface RouterInterface extends Slytherin { } diff --git a/src/Dispatching/Vanilla/Dispatcher.php b/src/Dispatching/Vanilla/Dispatcher.php index fa328882..7f830ce1 100644 --- a/src/Dispatching/Vanilla/Dispatcher.php +++ b/src/Dispatching/Vanilla/Dispatcher.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Dispatching\Vanilla; -use Rougin\Slytherin\Routing\Vanilla\Dispatcher as BaseDispatcher; +use Rougin\Slytherin\Routing\Vanilla\Dispatcher as Slytherin; /** * Dispatcher * - * A simple implementation of a route dispatcher that is based on DispatcherInterface. - * NOTE: To be removed in v1.0.0. Use "Routing\Dispatcher" instead. + * NOTE: To be removed in v1.0.0. Use "Routing\Vanilla\Dispatcher" instead. * * @package Slytherin * @author Rougin Gutib */ -class Dispatcher extends BaseDispatcher +class Dispatcher extends Slytherin { } diff --git a/src/Dispatching/Vanilla/Router.php b/src/Dispatching/Vanilla/Router.php index f56fe641..e58e3b71 100644 --- a/src/Dispatching/Vanilla/Router.php +++ b/src/Dispatching/Vanilla/Router.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Dispatching\Vanilla; -use Rougin\Slytherin\Routing\Vanilla\Router as BaseRouter; +use Rougin\Slytherin\Routing\Vanilla\Router as Slytherin; /** * Dispatcher * - * A simple implementation of a router that is based on RouterInterface. - * NOTE: To be removed in v1.0.0. Use "Routing\Router" instead. + * NOTE: To be removed in v1.0.0. Use "Routing\Vanilla\Router" instead. * * @package Slytherin * @author Rougin Gutib */ -class Router extends BaseRouter +class Router extends Slytherin { } diff --git a/src/Http/HttpIntegration.php b/src/Http/HttpIntegration.php index 9e9ab1e3..90b79a04 100644 --- a/src/Http/HttpIntegration.php +++ b/src/Http/HttpIntegration.php @@ -9,6 +9,7 @@ use Rougin\Slytherin\Http\ServerRequest; use Rougin\Slytherin\Integration\Configuration; use Rougin\Slytherin\Integration\IntegrationInterface; +use Rougin\Slytherin\System; use Zend\Diactoros\Response as ZendResponse; use Zend\Diactoros\ServerRequestFactory; @@ -124,26 +125,26 @@ protected function headers(array $server) */ protected function resolve(ContainerInterface $container, ServerRequestInterface $request, ResponseInterface $response) { - $empty = $this->preferred === null; + $class = 'Zend\Diactoros\ServerRequestFactory'; - $hasDiactoros = class_exists('Zend\Diactoros\ServerRequestFactory'); + $empty = $this->preferred === null; - $wantDiactoros = $this->preferred === 'diactoros'; + $wantZend = $this->preferred === 'diactoros'; - if (($empty || $wantDiactoros) && $hasDiactoros) + if (($empty || $wantZend) && class_exists($class)) { $response = new ZendResponse; $request = ServerRequestFactory::fromGlobals(); } - $container->set('Psr\Http\Message\ServerRequestInterface', $request); + $container->set(System::REQUEST, $request); - return $container->set('Psr\Http\Message\ResponseInterface', $response); + return $container->set(System::RESPONSE, $response); } /** - * Returns a sample $_SERVER values. + * Returns a sample of $_SERVER values. * * @return array */ diff --git a/src/Http/LICENSE.md b/src/Http/LICENSE.md index 6811efc9..5a9df18e 100644 --- a/src/Http/LICENSE.md +++ b/src/Http/LICENSE.md @@ -1,4 +1,4 @@ -Copyright (c) 2004-2018 Fabien Potencier +Copyright (c) 2004-2023 Fabien Potencier Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/src/Integration/Configuration.php b/src/Integration/Configuration.php index dd08baac..1e3d1b85 100644 --- a/src/Integration/Configuration.php +++ b/src/Integration/Configuration.php @@ -10,7 +10,7 @@ * @package Slytherin * @author Rougin Gutib */ -class Configuration implements ConfigurationInterface +class Configuration { /** * @var array @@ -48,10 +48,8 @@ public function get($key, $default = null) /** @var string */ $index = $keys[(int) $i]; - // TODO: Need to refactor ------ /** @phpstan-ignore-next-line */ $data = &$data[$index]; - // ----------------------------- } return $data !== null ? $data : $default; diff --git a/src/Integration/ConfigurationIntegration.php b/src/Integration/ConfigurationIntegration.php index e8348045..3934706c 100644 --- a/src/Integration/ConfigurationIntegration.php +++ b/src/Integration/ConfigurationIntegration.php @@ -5,6 +5,7 @@ use Rougin\Slytherin\Container\ContainerInterface; use Rougin\Slytherin\Integration\Configuration; use Rougin\Slytherin\Integration\IntegrationInterface; +use Rougin\Slytherin\System; /** * Configuration Integration @@ -25,10 +26,8 @@ class ConfigurationIntegration implements IntegrationInterface */ public function define(ContainerInterface $container, Configuration $config) { - $container->set('Rougin\Slytherin\Configuration', $config); + $alias = 'Rougin\Slytherin\Configuration'; - $container->set('Rougin\Slytherin\Integration\Configuration', $config); - - return $container; + return $container->set($alias, $config)->set(System::CONFIG, $config); } } diff --git a/src/Integration/ConfigurationInterface.php b/src/Integration/ConfigurationInterface.php deleted file mode 100644 index daac70ca..00000000 --- a/src/Integration/ConfigurationInterface.php +++ /dev/null @@ -1,23 +0,0 @@ - - */ -interface ConfigurationInterface -{ - /** - * Returns the value from the specified key. - * - * @param string $key - * @param mixed|null $default - * @return mixed - */ - public function get($key, $default = null); -} diff --git a/src/IoC/BaseContainer.php b/src/IoC/BaseContainer.php index 25790fe3..b7c6654f 100644 --- a/src/IoC/BaseContainer.php +++ b/src/IoC/BaseContainer.php @@ -5,8 +5,7 @@ /** * Base Container * - * A simple implementation of a container that is based on ContainerInterface. - * NOTE: To be removed in v1.0.0. Use "Container\Container" instead. + * NOTE: To be removed in v1.0.0. Use "Container" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/IoC/Container.php b/src/IoC/Container.php index aae51e3b..03fba8ad 100644 --- a/src/IoC/Container.php +++ b/src/IoC/Container.php @@ -5,8 +5,7 @@ /** * Container * - * A container that extends on Rougin\Slytherin\IoC\BaseContainer. - * NOTE: To be removed in v1.0.0. Use "Container\Container" instead. + * NOTE: To be removed in v1.0.0. Use "Vanilla\Container" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/IoC/DependencyInjectorInterface.php b/src/IoC/DependencyInjectorInterface.php new file mode 100644 index 00000000..d168907c --- /dev/null +++ b/src/IoC/DependencyInjectorInterface.php @@ -0,0 +1,15 @@ + + */ +interface DependencyInjectorInterface extends ContainerInterface +{ +} diff --git a/src/IoC/League/Container.php b/src/IoC/League/Container.php index c397977d..1261ab78 100644 --- a/src/IoC/League/Container.php +++ b/src/IoC/League/Container.php @@ -7,11 +7,8 @@ /** * LeagueContainer * - * A simple implementation of a container that is based on League\Container. * NOTE: To be removed in v1.0.0. Use "Container\LeagueContainer" instead. * - * http://container.thephpleague.com - * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/IoC/LeagueContainer.php b/src/IoC/LeagueContainer.php index 62fc5e02..2540eb83 100644 --- a/src/IoC/LeagueContainer.php +++ b/src/IoC/LeagueContainer.php @@ -5,10 +5,7 @@ /** * League Container * - * A simple implementation of a container that is based on League\Container. - * NOTE: To be removed in v1.0.0. Use "Container\LeagueContainer" instead. - * - * http://container.thephpleague.com + * NOTE: To be removed in v1.0.0. Use "League\Container" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/IoC/Vanilla/Container.php b/src/IoC/Vanilla/Container.php index dd142f0e..ca3a4a79 100644 --- a/src/IoC/Vanilla/Container.php +++ b/src/IoC/Vanilla/Container.php @@ -7,8 +7,7 @@ /** * Container * - * A container that extends on Rougin\Slytherin\IoC\BaseContainer. - * NOTE: To be removed in v1.0.0. Use "Container\Container" instead. + * NOTE: To be removed in v1.0.0. Use "Container\VanillaContainer" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/IoC/Vanilla/Exception/NotFoundException.php b/src/IoC/Vanilla/Exception/NotFoundException.php index 0248d3ba..6aeb0c68 100644 --- a/src/IoC/Vanilla/Exception/NotFoundException.php +++ b/src/IoC/Vanilla/Exception/NotFoundException.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\IoC\Vanilla\Exception; -use Rougin\Slytherin\Container\Exception\NotFoundException as BaseNotFoundException; +use Rougin\Slytherin\Container\Exception\NotFoundException as Slytherin; /** * Not Found Exception * - * A specified exception in handling errors in containers. * NOTE: To be removed in v1.0.0. Use "Container\Exception\NotFoundException" instead. * * @package Slytherin * @author Rougin Gutib */ -class NotFoundException extends BaseNotFoundException +class NotFoundException extends Slytherin { } diff --git a/src/Middleware/Callback.php b/src/Middleware/Callback.php index d0e3587b..b5c398c1 100644 --- a/src/Middleware/Callback.php +++ b/src/Middleware/Callback.php @@ -6,7 +6,9 @@ use Psr\Http\Message\ServerRequestInterface; /** - * Converts callables into Slytherin middlewares. + * Callback + * + * A class that converts callables into Slytherin middlewares. * * @package Slytherin * @author Rougin Gutib @@ -69,6 +71,8 @@ public function process(ServerRequestInterface $request, HandlerInterface $handl } /** + * Checks if the middleware is a single-pass or a double-pass implementation. + * * @param mixed $item * @return boolean */ diff --git a/src/Middleware/Delegate.php b/src/Middleware/Delegate.php index 53092c8d..57583e7c 100644 --- a/src/Middleware/Delegate.php +++ b/src/Middleware/Delegate.php @@ -3,7 +3,8 @@ namespace Rougin\Slytherin\Middleware; /** - * Calls the callback with a specified HTTP request. + * Delegate + * * NOTE: To be removed in v1.0.0. Use "Handler" instead. * * @package Slytherin diff --git a/src/Middleware/Dispatcher.php b/src/Middleware/Dispatcher.php index 6e333a1f..d0e877d4 100644 --- a/src/Middleware/Dispatcher.php +++ b/src/Middleware/Dispatcher.php @@ -6,6 +6,10 @@ use Rougin\Slytherin\Http\Response; /** + * Dispatcher + * + * A sample implementation of the middleware dispatcher. + * * @package Slytherin * @author Rougin Gutib */ @@ -30,6 +34,8 @@ public function __construct($stack = array()) } /** + * Returns the list of added middlewares. + * * @return \Rougin\Slytherin\Middleware\MiddlewareInterface[] */ public function getStack() @@ -38,6 +44,9 @@ public function getStack() } /** + * Process an incoming server request and return a response, optionally delegating + * to the next middleware component to create the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @param \Rougin\Slytherin\Middleware\HandlerInterface $handler * @return \Psr\Http\Message\ResponseInterface @@ -52,6 +61,8 @@ public function process(ServerRequestInterface $request, HandlerInterface $handl } /** + * Add a new middleware to the end of the stack. + * * @param mixed $middleware * @return self */ @@ -72,6 +83,8 @@ public function push($middleware) } /** + * Sets a new stack of middlewares. + * * @param mixed[] $stack * @return self */ @@ -90,6 +103,7 @@ public function setStack($stack) } /** + * Returns the list of added middlewares. * NOTE: To be removed in v1.0.0. Use "getStack" instead. * * @return \Rougin\Slytherin\Middleware\MiddlewareInterface[] @@ -100,6 +114,8 @@ public function stack() } /** + * Transforms the middleware into a Slytherin counterpart. + * * @param mixed $middleware * @return \Rougin\Slytherin\Middleware\MiddlewareInterface */ @@ -127,6 +143,8 @@ protected function transform($middleware) } /** + * Checks if the middleware is a callable. + * * @param mixed $item * @return boolean */ diff --git a/src/Middleware/DispatcherInterface.php b/src/Middleware/DispatcherInterface.php index 5f46435a..db9f8f33 100644 --- a/src/Middleware/DispatcherInterface.php +++ b/src/Middleware/DispatcherInterface.php @@ -5,7 +5,7 @@ /** * Dispatcher Interface * - * An interface for handling third party middleware dispatchers. + * An interface for handling third-party middleware dispatchers. * * @package Slytherin * @author Rougin Gutib @@ -13,17 +13,23 @@ interface DispatcherInterface extends MiddlewareInterface { /** + * Returns the list of added middlewares. + * * @return \Rougin\Slytherin\Middleware\MiddlewareInterface[] */ public function getStack(); /** + * Add a new middleware to the end of the stack. + * * @param mixed $middleware * @return self */ public function push($middleware); /** + * Sets a new stack of middlewares. + * * @param mixed[] $stack * @return self */ diff --git a/src/Middleware/Doublepass.php b/src/Middleware/Doublepass.php index 3da8d6b3..929ed099 100644 --- a/src/Middleware/Doublepass.php +++ b/src/Middleware/Doublepass.php @@ -6,6 +6,10 @@ use Psr\Http\Message\ServerRequestInterface; /** + * Doublepass + * + * A backward compatible handler to double-pass middlewares. + * * @package Slytherin * @author Rougin Gutib * @codeCoverageIgnore diff --git a/src/Middleware/Handler.php b/src/Middleware/Handler.php index 22878d80..ca558ac4 100644 --- a/src/Middleware/Handler.php +++ b/src/Middleware/Handler.php @@ -5,9 +5,12 @@ use Psr\Http\Message\ServerRequestInterface; /** + * Handler + * + * A default route for handling the application logic. + * * @package Slytherin * @author Rougin Gutib - * @codeCoverageIgnore */ class Handler implements HandlerInterface { @@ -38,6 +41,8 @@ public function __construct(array $stack, HandlerInterface $default) } /** + * Dispatch the next available middleware and return the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @return \Psr\Http\Message\ResponseInterface */ @@ -47,6 +52,8 @@ public function __invoke(ServerRequestInterface $request) } /** + * Dispatch the next available middleware and return the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @return \Psr\Http\Message\ResponseInterface */ @@ -65,6 +72,8 @@ public function handle(ServerRequestInterface $request) } /** + * Returns the next specified middleware. + * * @return \Rougin\Slytherin\Middleware\HandlerInterface */ protected function next() diff --git a/src/Middleware/HandlerInterface.php b/src/Middleware/HandlerInterface.php index 2db08a75..9ebee75d 100644 --- a/src/Middleware/HandlerInterface.php +++ b/src/Middleware/HandlerInterface.php @@ -15,6 +15,8 @@ interface HandlerInterface { /** + * Dispatch the next available middleware and return the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @return \Psr\Http\Message\ResponseInterface */ diff --git a/src/Middleware/Handlers/Handler030.php b/src/Middleware/Handlers/Handler030.php index 693dc8ad..5bdeb6f1 100644 --- a/src/Middleware/Handlers/Handler030.php +++ b/src/Middleware/Handlers/Handler030.php @@ -8,6 +8,10 @@ use Rougin\Slytherin\Middleware\HandlerInterface; /** + * PSR-15 Handler (v0.3.0) + * + * A handler that is backward compatible for the v0.3.0 version of "http-interop". + * * @package Slytherin * @author Rougin Gutib * @codeCoverageIgnore diff --git a/src/Middleware/Handlers/Handler041.php b/src/Middleware/Handlers/Handler041.php index 7874237c..cf907a00 100644 --- a/src/Middleware/Handlers/Handler041.php +++ b/src/Middleware/Handlers/Handler041.php @@ -7,6 +7,10 @@ use Rougin\Slytherin\Middleware\HandlerInterface; /** + * PSR-15 Handler (v0.4.1) + * + * A handler that is backward compatible for the v0.4.1 version of "http-interop". + * * @package Slytherin * @author Rougin Gutib * @codeCoverageIgnore diff --git a/src/Middleware/Handlers/Handler050.php b/src/Middleware/Handlers/Handler050.php index 5f333c20..f3fefd2c 100644 --- a/src/Middleware/Handlers/Handler050.php +++ b/src/Middleware/Handlers/Handler050.php @@ -7,6 +7,10 @@ use Rougin\Slytherin\Middleware\HandlerInterface; /** + * PSR-15 Handler (v0.5.0) + * + * A handler that is backward compatible for the v0.5.0 version of "http-interop". + * * @package Slytherin * @author Rougin Gutib * @codeCoverageIgnore diff --git a/src/Middleware/Handlers/Handler100.php b/src/Middleware/Handlers/Handler100.php index bff87f02..1fef631e 100644 --- a/src/Middleware/Handlers/Handler100.php +++ b/src/Middleware/Handlers/Handler100.php @@ -8,6 +8,10 @@ use Rougin\Slytherin\Middleware\HandlerInterface; /** + * PSR-15 Handler (v1.0.0) + * + * A handler that is backward compatible for the official implementation of PSR-15. + * * @package Slytherin * @author Rougin Gutib * @codeCoverageIgnore diff --git a/src/Middleware/Interop.php b/src/Middleware/Interop.php index ebf4190b..5d834314 100644 --- a/src/Middleware/Interop.php +++ b/src/Middleware/Interop.php @@ -9,6 +9,10 @@ use Rougin\Slytherin\Middleware\Handlers\Handler100; /** + * Interop Handler + * + * A handler that allows all "http-interop" middlewares to interact with Slytherin. + * * @package Slytherin * @author Rougin Gutib * @codeCoverageIgnore @@ -37,6 +41,8 @@ public function __construct($handler) } /** + * Dispatch the next available middleware and return the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @return \Psr\Http\Message\ResponseInterface */ @@ -46,6 +52,8 @@ public function __invoke(ServerRequestInterface $request) } /** + * Dispatch the next available middleware and return the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @return \Psr\Http\Message\ResponseInterface */ @@ -66,6 +74,8 @@ public function handle(ServerRequestInterface $request) } /** + * Checks if one of the supported versions are installed. + * * @return boolean */ public static function exists() @@ -76,6 +86,8 @@ public static function exists() } /** + * Converts the handler into the currently installed PSR-15 implementation. + * * @param mixed $handler * @param string|null $version * @return mixed @@ -121,6 +133,8 @@ public static function getHandler($handler, $version = null) } /** + * Checks if the handler is installed in the supported PSR-15 version. + * * @param mixed $handler * @param string $version * @return boolean @@ -131,6 +145,8 @@ public static function hasVersion($handler, $class) } /** + * Checks if the official PSR-15 is currently installed. + * * @return boolean */ public static function psrExists() diff --git a/src/Middleware/Middleware.php b/src/Middleware/Middleware.php index 9fac26fb..c06540b7 100644 --- a/src/Middleware/Middleware.php +++ b/src/Middleware/Middleware.php @@ -5,8 +5,7 @@ /** * Middleware * - * A simple implementation of a middleware dispatcher. - * NOTE: To be removed in v1.0.0. Use "Middleware\Dispatcher" instead. + * NOTE: To be removed in v1.0.0. Use "Dispatcher" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Middleware/MiddlewareInterface.php b/src/Middleware/MiddlewareInterface.php index aa27c5e3..a2be8fad 100644 --- a/src/Middleware/MiddlewareInterface.php +++ b/src/Middleware/MiddlewareInterface.php @@ -15,6 +15,9 @@ interface MiddlewareInterface { /** + * Process an incoming server request and return a response, optionally delegating + * to the next middleware component to create the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @param \Rougin\Slytherin\Middleware\HandlerInterface $handler * @return \Psr\Http\Message\ResponseInterface diff --git a/src/Middleware/Stratigility/Middleware.php b/src/Middleware/Stratigility/Middleware.php index 3c8216ed..8552fe58 100644 --- a/src/Middleware/Stratigility/Middleware.php +++ b/src/Middleware/Stratigility/Middleware.php @@ -2,18 +2,16 @@ namespace Rougin\Slytherin\Middleware\Stratigility; -use Rougin\Slytherin\Middleware\StratigilityMiddleware; +use Rougin\Slytherin\Middleware\StratigilityDispatcher; /** * Stratigility Middleware * - * A simple implementation of middleware that is built on top of Stratigility. * NOTE: To be removed in v1.0.0. Use "Middleware\StratigilityDispatcher" instead. * * @package Slytherin * @author Rougin Gutib - * @link https://github.com/zendframework/zend-stratigility */ -class Middleware extends StratigilityMiddleware +class Middleware extends StratigilityDispatcher { } diff --git a/src/Middleware/StratigilityDispatcher.php b/src/Middleware/StratigilityDispatcher.php index ca640550..69bd730d 100644 --- a/src/Middleware/StratigilityDispatcher.php +++ b/src/Middleware/StratigilityDispatcher.php @@ -18,7 +18,8 @@ * * @package Slytherin * @author Rougin Gutib - * @link https://github.com/zendframework/zend-stratigility + * + * @link https://github.com/zendframework/zend-stratigility */ class StratigilityDispatcher extends Dispatcher { @@ -39,6 +40,8 @@ public function __construct(MiddlewarePipe $pipe, $stack = array()) } /** + * Checks if the current version has a wrapper factory. + * * @return boolean */ public function hasFactory() @@ -47,6 +50,8 @@ public function hasFactory() } /** + * Checks if the current version implements the official PSR-15. + * * @return boolean */ public function hasPsr() @@ -55,6 +60,9 @@ public function hasPsr() } /** + * Process an incoming server request and return a response, optionally delegating + * to the next middleware component to create the response. + * * @param \Psr\Http\Message\ServerRequestInterface $request * @param \Rougin\Slytherin\Middleware\HandlerInterface $handler * @return \Psr\Http\Message\ResponseInterface @@ -69,10 +77,12 @@ public function process(ServerRequestInterface $request, HandlerInterface $handl { $item = $this->setMiddleware($item); + // @codeCoverageIgnoreStart if (! $this->hasFactory() && $this->hasPsr()) { $item = $this->setPsrMiddleware($item); } + // @codeCoverageIgnoreEnd $this->zend->pipe($item); } @@ -85,17 +95,21 @@ public function process(ServerRequestInterface $request, HandlerInterface $handl $zend = $this->zend; + // @codeCoverageIgnoreStart if ($this->hasPsr()) { /** @phpstan-ignore-next-line */ return $zend->process($request, $next); } + // @codeCoverageIgnoreEnd /** @phpstan-ignore-next-line */ return $zend($request, $response, $next); } /** + * Sets the factory if there is a middleware decorator. + * * @param \Psr\Http\Message\ResponseInterface $response * @return void * @codeCoverageIgnore @@ -118,11 +132,14 @@ protected function setFactory(ResponseInterface $response) } /** + * Sets the Slytherin middleware into a single-pass or double-pass callable. + * * @param \Rougin\Slytherin\Middleware\MiddlewareInterface $item * @return callable */ protected function setMiddleware(MiddlewareInterface $item) { + // @codeCoverageIgnoreStart if ($this->hasPsr()) { return function ($request, $handler) use ($item) @@ -130,6 +147,7 @@ protected function setMiddleware(MiddlewareInterface $item) return $item->process($request, new Interop($handler)); }; } + // @codeCoverageIgnoreEnd return function ($request, $response, $next) use ($item) { @@ -141,6 +159,8 @@ protected function setMiddleware(MiddlewareInterface $item) } /** + * Sets the PSR-15 decorator to a middleware. + * * @param callable $item * @return object * @codeCoverageIgnore diff --git a/src/Middleware/StratigilityMiddleware.php b/src/Middleware/StratigilityMiddleware.php index 4f1a97d5..95dbde79 100644 --- a/src/Middleware/StratigilityMiddleware.php +++ b/src/Middleware/StratigilityMiddleware.php @@ -5,13 +5,11 @@ /** * Stratigility Middleware * - * A simple implementation of middleware that is built on top of Zend's Stratigility. - * NOTE: To be removed in v1.0.0. Use "Middleware\StratigilityDispatcher" instead. + * NOTE: To be removed in v1.0.0. Use "Stratigility\Middleware" instead. * * @package Slytherin * @author Rougin Gutib - * @link https://github.com/zendframework/zend-stratigility */ -class StratigilityMiddleware extends StratigilityDispatcher +class StratigilityMiddleware extends Stratigility\Middleware { } diff --git a/src/Middleware/Vanilla/Delegate.php b/src/Middleware/Vanilla/Delegate.php index 665c673b..90c4b25a 100644 --- a/src/Middleware/Vanilla/Delegate.php +++ b/src/Middleware/Vanilla/Delegate.php @@ -2,18 +2,16 @@ namespace Rougin\Slytherin\Middleware\Vanilla; -use Rougin\Slytherin\Middleware\VanillaDelegate; +use Rougin\Slytherin\Middleware\Delegate as Slytherin; /** * Delegate * - * Calls the callback with a specified HTTP request. - * NOTE: To be removed in v1.0.0. Use "Middleware\Delegate" instead. + * NOTE: To be removed in v1.0.0. Use "Delegate" instead. * * @package Slytherin * @author Rougin Gutib - * @author Rasmus Schultz */ -class Delegate extends VanillaDelegate +class Delegate extends Slytherin { } diff --git a/src/Middleware/Vanilla/Middleware.php b/src/Middleware/Vanilla/Middleware.php index 2611b8e9..ca7e1250 100644 --- a/src/Middleware/Vanilla/Middleware.php +++ b/src/Middleware/Vanilla/Middleware.php @@ -2,18 +2,16 @@ namespace Rougin\Slytherin\Middleware\Vanilla; -use Rougin\Slytherin\Middleware\VanillaMiddleware; +use Rougin\Slytherin\Middleware\Middleware as Slytherin; /** * Middleware * - * A simple implementation of a middleware on PSR-15. - * NOTE: To be removed in v1.0.0. Use "Middleware\Dispatcher" instead. + * NOTE: To be removed in v1.0.0. Use "Middleware" instead. * * @package Slytherin * @author Rougin Gutib - * @author Rasmus Schultz */ -class Middleware extends VanillaMiddleware +class Middleware extends Slytherin { } diff --git a/src/Middleware/VanillaDelegate.php b/src/Middleware/VanillaDelegate.php index 27081997..e0da8f42 100644 --- a/src/Middleware/VanillaDelegate.php +++ b/src/Middleware/VanillaDelegate.php @@ -3,12 +3,13 @@ namespace Rougin\Slytherin\Middleware; /** - * Calls the callback with a specified HTTP request. - * NOTE: To be removed in v1.0.0. Use "Middleware\Delegate" instead. + * Delegate + * + * NOTE: To be removed in v1.0.0. Use "Vanilla\Delegate" instead. * * @package Slytherin * @author Rougin Gutib */ -class VanillaDelegate extends Delegate +class VanillaDelegate extends Vanilla\Delegate { } diff --git a/src/Middleware/VanillaMiddleware.php b/src/Middleware/VanillaMiddleware.php index 6be7a360..a93708ee 100644 --- a/src/Middleware/VanillaMiddleware.php +++ b/src/Middleware/VanillaMiddleware.php @@ -5,12 +5,11 @@ /** * Middleware * - * A simple implementation of a middleware. - * NOTE: To be removed in v1.0.0. Use "Middleware\Dispatcher" instead. + * NOTE: To be removed in v1.0.0. Use "Vanilla\Middleware" instead. * * @package Slytherin * @author Rougin Gutib */ -class VanillaMiddleware extends Middleware +class VanillaMiddleware extends Vanilla\Middleware { } diff --git a/src/Middleware/Version.php b/src/Middleware/Version.php index 5775f4d8..d6a9b1f4 100644 --- a/src/Middleware/Version.php +++ b/src/Middleware/Version.php @@ -3,6 +3,10 @@ namespace Rougin\Slytherin\Middleware; /** + * Version + * + * A simple class for getting the current installed version of "http-interop". + * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/Middleware/Wrapper.php b/src/Middleware/Wrapper.php index 66f4afcb..4ad5abc9 100644 --- a/src/Middleware/Wrapper.php +++ b/src/Middleware/Wrapper.php @@ -5,7 +5,9 @@ use Psr\Http\Message\ServerRequestInterface; /** - * Converts various middlewares into Slytherin counterparts. + * Wrapper + * + * A middleware that converts various middlewares into its Slytherin counterpart. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Routing/DispatcherInterface.php b/src/Routing/DispatcherInterface.php index 864eba24..c51167fa 100644 --- a/src/Routing/DispatcherInterface.php +++ b/src/Routing/DispatcherInterface.php @@ -5,7 +5,7 @@ /** * Dispatcher Interface * - * An interface for handling third party route dispatchers. + * An interface for handling third-party route dispatchers. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Routing/FastRoute/Dispatcher.php b/src/Routing/FastRoute/Dispatcher.php index e6c1c177..f1e25b13 100644 --- a/src/Routing/FastRoute/Dispatcher.php +++ b/src/Routing/FastRoute/Dispatcher.php @@ -7,11 +7,8 @@ /** * FastRoute Dispatcher * - * A simple implementation of dispatcher that is built on top of FastRoute. * NOTE: To be removed in v1.0.0. Use "Routing\FastRouteDispatcher" instead. * - * https://github.com/nikic/FastRoute - * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/Routing/FastRoute/Router.php b/src/Routing/FastRoute/Router.php index f3f8b2be..f8ce23fa 100644 --- a/src/Routing/FastRoute/Router.php +++ b/src/Routing/FastRoute/Router.php @@ -7,11 +7,8 @@ /** * FastRoute Router * - * A simple implementation of router that is built on top of FastRoute. * NOTE: To be removed in v1.0.0. Use "Routing\FastRouteRouter" instead. * - * https://github.com/nikic/FastRoute - * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/Routing/FastRouteDispatcher.php b/src/Routing/FastRouteDispatcher.php index 44703627..401069c9 100644 --- a/src/Routing/FastRouteDispatcher.php +++ b/src/Routing/FastRouteDispatcher.php @@ -7,10 +7,10 @@ * * A simple implementation of dispatcher that is built on top of FastRoute. * - * https://github.com/nikic/FastRoute - * * @package Slytherin * @author Rougin Gutib + * + * @link https://github.com/nikic/FastRoute */ class FastRouteDispatcher extends Dispatcher { @@ -47,7 +47,7 @@ public function dispatch($method, $uri) /** @var \Rougin\Slytherin\Routing\RouteInterface */ $route = $result[1]; - /** @var string[] */ + /** @var array */ $params = $result[2]; return $route->setParams($params); diff --git a/src/Routing/FastRouteRouter.php b/src/Routing/FastRouteRouter.php index 9119010a..76e51791 100644 --- a/src/Routing/FastRouteRouter.php +++ b/src/Routing/FastRouteRouter.php @@ -11,10 +11,10 @@ * * A simple implementation of router that is built on top of FastRoute. * - * https://github.com/nikic/FastRoute - * * @package Slytherin * @author Rougin Gutib + * + * @link https://github.com/nikic/FastRoute */ class FastRouteRouter extends Router { @@ -57,7 +57,21 @@ public function parsed(array $routes = array()) { foreach ($routes as $route) { - $collector->addRoute($route->getMethod(), $route->getUri(), $route); + // Convert the ":name" pattern into "{name}" pattern ------------------ + $uri = $route->getUri(); + + $matched = preg_match_all('/\:([a-zA-Z0-9\_\-]+)/i', $uri, $matches); + + if ($matched) + { + foreach ($matches[0] as $key => $item) + { + $uri = str_replace($item, '{' . $matches[1][$key] . '}', $uri); + } + } + // -------------------------------------------------------------------- + + $collector->addRoute($route->getMethod(), $uri, $route); } }; diff --git a/src/Routing/Phroute/Dispatcher.php b/src/Routing/Phroute/Dispatcher.php index 46e85244..c5dad492 100644 --- a/src/Routing/Phroute/Dispatcher.php +++ b/src/Routing/Phroute/Dispatcher.php @@ -7,11 +7,8 @@ /** * Phroute Dispatcher * - * A simple implementation of dispatcher that is built on top of Phroute. * NOTE: To be removed in v1.0.0. Use "Routing\PhrouteDispatcher" instead. * - * https://github.com/mrjgreen/phroute - * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/Routing/Phroute/Router.php b/src/Routing/Phroute/Router.php index 3bcefec1..f501831b 100644 --- a/src/Routing/Phroute/Router.php +++ b/src/Routing/Phroute/Router.php @@ -7,11 +7,8 @@ /** * Phroute Router * - * A simple implementation of router that is built on top of Phroute. * NOTE: To be removed in v1.0.0. Use "Routing\PhrouteRouter" instead. * - * https://github.com/mrjgreen/phroute - * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/Routing/PhrouteDispatcher.php b/src/Routing/PhrouteDispatcher.php index 99c37059..9b395c1e 100644 --- a/src/Routing/PhrouteDispatcher.php +++ b/src/Routing/PhrouteDispatcher.php @@ -12,10 +12,10 @@ * * A simple implementation of dispatcher that is built on top of Phroute. * - * https://github.com/mrjgreen/phroute - * * @package Slytherin * @author Rougin Gutib + * + * @link https://github.com/mrjgreen/phroute */ class PhrouteDispatcher extends Dispatcher { @@ -73,7 +73,27 @@ public function dispatch($method, $uri) try { /** @var \Rougin\Slytherin\Routing\RouteInterface */ - return $phroute->dispatch($method, $uri); + $route = $phroute->dispatch($method, $uri); + + // Combine values from resolver and the current parameters ------------- + $regex = '/\{([a-zA-Z0-9\_\-]+)\}/i'; + + $matched = preg_match_all($regex, $route->getUri(), $matches); + + // If "{name}" pattern is not found, try the ":name" pattern instead --- + if (! $matched) + { + $regex = '/\:([a-zA-Z0-9\_\-]+)/i'; + + $matched = preg_match_all($regex, $route->getUri(), $matches); + } + // --------------------------------------------------------------------- + + /** @var array */ + $params = array_combine($matches[1], $route->getParams()); + + return $route->setParams($params); + // --------------------------------------------------------------------- } catch (HttpRouteNotFoundException $e) { diff --git a/src/Routing/PhrouteResolver.php b/src/Routing/PhrouteResolver.php index 88c5a07f..f4e1e44b 100644 --- a/src/Routing/PhrouteResolver.php +++ b/src/Routing/PhrouteResolver.php @@ -9,10 +9,10 @@ * * A handler resolver that wraps the route as the result. * - * https://github.com/mrjgreen/phroute - * * @package Slytherin * @author Rougin Gutib + * + * @link https://github.com/mrjgreen/phroute */ class PhrouteResolver implements HandlerResolverInterface { diff --git a/src/Routing/PhrouteRouter.php b/src/Routing/PhrouteRouter.php index f8a7aa58..5ef442be 100644 --- a/src/Routing/PhrouteRouter.php +++ b/src/Routing/PhrouteRouter.php @@ -9,10 +9,10 @@ * * A simple implementation of router that is built on top of Phroute. * - * https://github.com/mrjgreen/phroute - * * @package Slytherin * @author Rougin Gutib + * + * @link https://github.com/mrjgreen/phroute */ class PhrouteRouter extends Router { @@ -63,7 +63,21 @@ public function asParsed(array $routes) { foreach ($routes as $route) { - $this->collector->addRoute($route->getMethod(), $route->getUri(), $route); + // Convert the ":name" pattern into "{name}" pattern ------------------ + $uri = $route->getUri(); + + $matched = preg_match_all('/\:([a-zA-Z0-9\_\-]+)/i', $uri, $matches); + + if ($matched) + { + foreach ($matches[0] as $key => $item) + { + $uri = str_replace($item, '{' . $matches[1][$key] . '}', $uri); + } + } + // -------------------------------------------------------------------- + + $this->collector->addRoute($route->getMethod(), $uri, $route); } return $this->collector->getData(); diff --git a/src/Routing/PhrouteWrapper.php b/src/Routing/PhrouteWrapper.php index 20def995..0e1a951f 100644 --- a/src/Routing/PhrouteWrapper.php +++ b/src/Routing/PhrouteWrapper.php @@ -3,12 +3,14 @@ namespace Rougin\Slytherin\Routing; /** - * A simple class wrapper for resolving routes in Phroute. + * Phroute Wrapper * - * https://github.com/mrjgreen/phroute + * A simple class wrapper for resolving routes in Phroute. * * @package Slytherin * @author Rougin Gutib + * + * @link https://github.com/mrjgreen/phroute */ class PhrouteWrapper { diff --git a/src/Routing/Route.php b/src/Routing/Route.php index c3fe37b3..95d74dc7 100644 --- a/src/Routing/Route.php +++ b/src/Routing/Route.php @@ -3,6 +3,10 @@ namespace Rougin\Slytherin\Routing; /** + * Route + * + * A simple class for handling routes. + * * @package Slytherin * @author Rougin Gutib */ @@ -24,7 +28,7 @@ class Route implements RouteInterface protected $middlewares; /** - * @var string[] + * @var array */ protected $params = array(); @@ -62,6 +66,8 @@ public function __construct($method, $uri, $handler, $middlewares = array()) } /** + * Returns the handler. + * * @return callable|string[]|string */ public function getHandler() @@ -70,6 +76,8 @@ public function getHandler() } /** + * Returns the HTTP method. + * * @return string */ public function getMethod() @@ -78,6 +86,8 @@ public function getMethod() } /** + * Returns the defined middlewares. + * * @return mixed[] */ public function getMiddlewares() @@ -86,7 +96,9 @@ public function getMiddlewares() } /** - * @return string[] + * Returns the defined parameters. + * + * @return array */ public function getParams() { @@ -96,9 +108,9 @@ public function getParams() /** * Returns a regular expression pattern from the given URI. * - * @link https://stackoverflow.com/q/30130913 - * * @return string + * + * @link https://stackoverflow.com/q/30130913 */ public function getRegex() { @@ -121,6 +133,8 @@ public function getRegex() } /** + * Return the URI of the route. + * * @return string */ public function getUri() @@ -129,28 +143,28 @@ public function getUri() } /** - * Capture the specified regular expressions. + * Sets the parameters to the route. * - * @param string $pattern - * @param string $search - * @return string + * @param array $params + * @return self */ - protected function capture($pattern, $search) + public function setParams($params) { - $replace = '(?<$1>' . self::ALLOWED_REGEX . ')'; + $this->params = $params; - /** @var string */ - return preg_replace($search, $replace, $pattern); + return $this; } /** - * @param string[] $params - * @return self + * Capture the specified regular expressions. + * + * @param string $pattern + * @param string $search + * @return string */ - public function setParams($params) + protected function capture($pattern, $search) { - $this->params = $params; - - return $this; + /** @var string */ + return preg_replace($search, '(?<$1>' . self::ALLOWED_REGEX . ')', $pattern); } } diff --git a/src/Routing/RouteInterface.php b/src/Routing/RouteInterface.php index bd181900..fb66a896 100644 --- a/src/Routing/RouteInterface.php +++ b/src/Routing/RouteInterface.php @@ -3,6 +3,10 @@ namespace Rougin\Slytherin\Routing; /** + * Route Interface + * + * An interface for handling the HTTP routes. + * * @package Slytherin * @author Rougin Gutib */ @@ -11,38 +15,50 @@ interface RouteInterface const ALLOWED_REGEX = '[a-zA-Z0-9\_\-]+'; /** + * Returns the handler. + * * @return callable|string[]|string */ public function getHandler(); /** + * Returns the HTTP method. + * * @return string */ public function getMethod(); /** + * Returns the defined middlewares. + * * @return mixed[] */ public function getMiddlewares(); /** + * Returns the defined parameters. + * * @return string[] */ public function getParams(); /** - * Returns a regular expression from URI. + * Returns a regular expression pattern from the given URI. * * @return string */ public function getRegex(); /** + * Return the URI of the route. + * * @return string */ public function getUri(); /** + * Sets the parameters to the route. + * * @param string[] $params * @return self */ diff --git a/src/Routing/Router.php b/src/Routing/Router.php index fb9dbfa9..44641e06 100644 --- a/src/Routing/Router.php +++ b/src/Routing/Router.php @@ -61,7 +61,7 @@ public function __construct(array $routes = array()) /** * Adds a new raw route. * - * @param string $method + * @param string $method * @param string $uri * @param callable|string[]|string $handler * @param \Rougin\Slytherin\Middleware\MiddlewareInterface[]|string[] $middlewares @@ -100,9 +100,9 @@ public function add($method, $uri, $handler, $middlewares = array()) * Adds a new raw route. * NOTE: To be removed in v1.0.0. Use "add" instead. * - * @param string $method - * @param string $route - * @param callable|string[]|string $handler + * @param string $method + * @param string $route + * @param callable|string[]|string $handler * @param \Rougin\Slytherin\Middleware\MiddlewareInterface[]|string[] $middlewares * @return self */ diff --git a/src/Routing/RouterInterface.php b/src/Routing/RouterInterface.php index 145d49e1..aca5c5ab 100644 --- a/src/Routing/RouterInterface.php +++ b/src/Routing/RouterInterface.php @@ -5,7 +5,7 @@ /** * Router Interface * - * An interface for handling third party routers. + * An interface for handling third-party routers. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Routing/RoutingIntegration.php b/src/Routing/RoutingIntegration.php index 1e729649..ace96a6a 100644 --- a/src/Routing/RoutingIntegration.php +++ b/src/Routing/RoutingIntegration.php @@ -5,6 +5,7 @@ use Rougin\Slytherin\Container\ContainerInterface; use Rougin\Slytherin\Integration\Configuration; use Rougin\Slytherin\Integration\IntegrationInterface; +use Rougin\Slytherin\System; /** * Routing Integration @@ -30,34 +31,51 @@ class RoutingIntegration implements IntegrationInterface */ public function define(ContainerInterface $container, Configuration $config) { - $hasFastroute = interface_exists('FastRoute\Dispatcher'); + $dispatcher = new Dispatcher; - $wantFastroute = $this->preferred === 'fastroute'; + $router = $config->get('app.router', new Router); - $hasPhroute = class_exists('Phroute\Phroute\Dispatcher'); + if ($this->wants('fastroute')) + { + $dispatcher = new FastRouteDispatcher; + } - $wantPhroute = $this->preferred === 'phroute'; + if ($this->wants('phroute')) + { + $dispatcher = new PhrouteDispatcher; + } - $dispatcher = new Dispatcher; + $container->set(System::DISPATCHER, $dispatcher); - $router = $config->get('app.router', new Router); + return $container->set(System::ROUTER, $router); + } + /** + * Checks the preferred package to be used. + * + * @param string $type + * @return boolean + */ + protected function wants($type) + { $empty = $this->preferred === null; - if (($empty || $wantFastroute) && $hasFastroute) + $package = ''; + + if ($type === 'fastroute') { - $dispatcher = new FastRouteDispatcher; + $package = 'FastRoute\RouteCollector'; } - if (($empty || $wantPhroute) && $hasPhroute) + if ($type === 'phroute') { - $dispatcher = new PhrouteDispatcher; + $package = 'Phroute\Phroute\Dispatcher'; } - $container->set('Rougin\Slytherin\Routing\DispatcherInterface', $dispatcher); + $preferred = $this->preferred === $type; - $container->set('Rougin\Slytherin\Routing\RouterInterface', $router); + $exists = class_exists($package); - return $container; + return ($empty || $preferred) && $exists; } } diff --git a/src/Routing/Vanilla/Dispatcher.php b/src/Routing/Vanilla/Dispatcher.php index 62f095e8..497f9c82 100644 --- a/src/Routing/Vanilla/Dispatcher.php +++ b/src/Routing/Vanilla/Dispatcher.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Routing\Vanilla; -use Rougin\Slytherin\Routing\Dispatcher as VanillaDispatcher; +use Rougin\Slytherin\Routing\Dispatcher as Slytherin; /** * Dispatcher * - * A simple implementation of a route dispatcher that is based on DispatcherInterface. * NOTE: To be removed in v1.0.0. Use "Routing\Dispatcher" instead. * * @package Slytherin * @author Rougin Gutib */ -class Dispatcher extends VanillaDispatcher +class Dispatcher extends Slytherin { } diff --git a/src/Routing/Vanilla/Router.php b/src/Routing/Vanilla/Router.php index 1477d0c0..d5b3ba47 100644 --- a/src/Routing/Vanilla/Router.php +++ b/src/Routing/Vanilla/Router.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Routing\Vanilla; -use Rougin\Slytherin\Routing\Router as VanillaRouter; +use Rougin\Slytherin\Routing\Router as Slytherin; /** * Router * - * A simple implementation of a router that is based on RouterInterface. * NOTE: To be removed in v1.0.0. Use "Routing\Router" instead. * * @package Slytherin * @author Rougin Gutib */ -class Router extends VanillaRouter +class Router extends Slytherin { } diff --git a/src/System.php b/src/System.php index cfb4f98c..b0f01c07 100644 --- a/src/System.php +++ b/src/System.php @@ -6,7 +6,7 @@ use Rougin\Slytherin\Component\Collection; use Rougin\Slytherin\Container\Container; use Rougin\Slytherin\Container\ContainerInterface; -use Rougin\Slytherin\Integration\ConfigurationInterface; +use Rougin\Slytherin\Integration\Configuration; use Rougin\Slytherin\System\Handler; /** @@ -19,13 +19,13 @@ */ class System { - const CONTAINER = 'Rougin\Slytherin\Container\ContainerInterface'; + const CONFIG = 'Rougin\Slytherin\Integration\Configuration'; - const DISPATCHER = 'Rougin\Slytherin\Routing\DispatcherInterface'; + const CONTAINER = 'Rougin\Slytherin\Container\ContainerInterface'; - // TODO: Implement Error Handler ------------------------------- const DEBUGGER = 'Rougin\Slytherin\Debug\ErrorHandlerInterface'; - // ------------------------------------------------------------- + + const DISPATCHER = 'Rougin\Slytherin\Routing\DispatcherInterface'; const MIDDLEWARE = 'Rougin\Slytherin\Middleware\DispatcherInterface'; @@ -53,7 +53,7 @@ class System * @param mixed|null $container * @param \Rougin\Slytherin\Integration\Configuration|null $config */ - public function __construct($container = null, ConfigurationInterface $config = null) + public function __construct($container = null, Configuration $config = null) { if (! $config) $config = new Configuration; @@ -72,20 +72,6 @@ public function __construct($container = null, ConfigurationInterface $config = } } - /** - * Finds an entry of the container by its identifier and returns it. - * - * @throws \Psr\Container\NotFoundExceptionInterface - * @throws \Psr\Container\ContainerExceptionInterface - * - * @param string $id - * @return mixed - */ - public function get($id) - { - return $this->container->get($id); - } - /** * Handles the ServerRequestInterface to convert it to a ResponseInterface. * @@ -133,22 +119,28 @@ public function handle(ServerRequestInterface $request) /** * Adds the specified integrations to the container. * - * @param \Rougin\Slytherin\Integration\IntegrationInterface[]|string[]|string $integrations - * @param \Rougin\Slytherin\Integration\Configuration|null $config + * @param mixed[]|string $items + * @param \Rougin\Slytherin\Integration\Configuration|null $config * @return self */ - public function integrate($integrations, ConfigurationInterface $config = null) + public function integrate($items, Configuration $config = null) { if (! $config) $config = $this->config; + if (is_string($items)) $items = array($items); + $container = $this->container; - foreach ((array) $integrations as $item) + /** @var \Rougin\Slytherin\Integration\IntegrationInterface|string $item */ + foreach ($items as $item) { - /** @var \Rougin\Slytherin\Integration\IntegrationInterface */ - $integration = is_string($item) ? new $item : $item; + if (is_string($item)) + { + /** @var \Rougin\Slytherin\Integration\IntegrationInterface */ + $item = new $item; + } - $container = $integration->define($container, $config); + $container = $item->define($container, $config); } $this->container = $container; @@ -163,6 +155,14 @@ public function integrate($integrations, ConfigurationInterface $config = null) */ public function run() { + if ($this->container->has(self::DEBUGGER)) + { + /** @var \Rougin\Slytherin\Debug\ErrorHandlerInterface */ + $debugger = $this->container->get(self::DEBUGGER); + + $debugger->display(); + } + /** @var \Psr\Http\Message\ServerRequestInterface */ $request = $this->container->get(self::REQUEST); @@ -171,7 +171,6 @@ public function run() /** * Emits the headers based from the response. - * NOTE: To be removed in v1.0.0. Should be included in run(). * * @param \Psr\Http\Message\ServerRequestInterface $request * @return \Psr\Http\Message\ResponseInterface diff --git a/src/System/Endofline.php b/src/System/Endofline.php index 7af3de8e..99920e4a 100644 --- a/src/System/Endofline.php +++ b/src/System/Endofline.php @@ -7,6 +7,10 @@ use Rougin\Slytherin\Middleware\HandlerInterface; /** + * End of Line (EOL) + * + * A handler that only returns an empty HTTP response. + * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/System/Handler.php b/src/System/Handler.php index fd23a2d8..2baef781 100644 --- a/src/System/Handler.php +++ b/src/System/Handler.php @@ -10,6 +10,8 @@ use Rougin\Slytherin\System; /** + * Callback Handler + * * Builds the final callback after handling from application. * * @package Slytherin diff --git a/src/System/Resolver.php b/src/System/Resolver.php index ebea36b4..046eefc3 100644 --- a/src/System/Resolver.php +++ b/src/System/Resolver.php @@ -8,6 +8,10 @@ use Rougin\Slytherin\Container\ReflectionContainer; /** + * Resolver + * + * Resolves the identifier from the container. + * * @package Slytherin * @author Rougin Gutib */ diff --git a/src/Template/RendererInterface.php b/src/Template/RendererInterface.php index 8af768c1..8c259b37 100644 --- a/src/Template/RendererInterface.php +++ b/src/Template/RendererInterface.php @@ -5,7 +5,7 @@ /** * Renderer Interface * - * An interface for handling third party template engines. + * An interface for handling third-party template engines. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Template/Twig.php b/src/Template/Twig.php index 0a257e1f..5cceec26 100644 --- a/src/Template/Twig.php +++ b/src/Template/Twig.php @@ -3,13 +3,13 @@ namespace Rougin\Slytherin\Template; /** - * Renderer + * Twig Renderer * - * NOTE: To be removed in v1.0.0. Use "TwigRenderer" instead. + * NOTE: To be removed in v1.0.0. Use "Twig\Renderer" instead. * * @package Slytherin * @author Rougin Gutib */ -class Twig extends TwigRenderer +class Twig extends Twig\Renderer { } diff --git a/src/Template/Twig/Renderer.php b/src/Template/Twig/Renderer.php index e487b67a..316f5535 100644 --- a/src/Template/Twig/Renderer.php +++ b/src/Template/Twig/Renderer.php @@ -5,9 +5,9 @@ use Rougin\Slytherin\Template\TwigRenderer; /** - * Renderer + * Twig Renderer * - * NOTE: To be removed in v1.0.0. Use "Template\TwigRenderer" instead. + * NOTE: To be removed in v1.0.0. Use "TwigRenderer" instead. * * @package Slytherin * @author Rougin Gutib diff --git a/src/Template/TwigLoader.php b/src/Template/TwigLoader.php index a1fdfd88..b4ce288e 100644 --- a/src/Template/TwigLoader.php +++ b/src/Template/TwigLoader.php @@ -5,7 +5,7 @@ /** * Twig Loader * - * Backward compatibility for the Twig package. + * A backward compatibility class for the Twig package. * * @package Slytherin * @author Rougin Gutib @@ -13,6 +13,8 @@ class TwigLoader { /** + * Check if any version of Twig is installed. + * * @return boolean */ public function exists() @@ -21,6 +23,8 @@ public function exists() } /** + * Loads the Twig instance. + * * @param string|string[] $path * @return \Twig\Environment */ diff --git a/src/Template/TwigRenderer.php b/src/Template/TwigRenderer.php index a177e215..f6684dc2 100644 --- a/src/Template/TwigRenderer.php +++ b/src/Template/TwigRenderer.php @@ -8,10 +8,10 @@ * A simple implementation of a template renderer that is based on top of * Sensiolab's Twig - a flexible, fast, and secure template engine for PHP. * - * http://twig.sensiolabs.org - * * @package Slytherin * @author Rougin Gutib + * + * @link http://twig.sensiolabs.org */ class TwigRenderer implements RendererInterface { diff --git a/src/Template/Vanilla/Renderer.php b/src/Template/Vanilla/Renderer.php index 8afebd93..4e8dde86 100644 --- a/src/Template/Vanilla/Renderer.php +++ b/src/Template/Vanilla/Renderer.php @@ -2,17 +2,16 @@ namespace Rougin\Slytherin\Template\Vanilla; -use Rougin\Slytherin\Template\VanillaRenderer; +use Rougin\Slytherin\Template\Renderer as Slytherin; /** * Renderer * - * A simple implementation of a template renderer. - * NOTE: To be removed in v1.0.0. Use "Template\Renderer" instead. + * NOTE: To be removed in v1.0.0. Use "Renderer" instead. * * @package Slytherin * @author Rougin Gutib */ -class Renderer extends VanillaRenderer +class Renderer extends Slytherin { } diff --git a/src/Template/VanillaRenderer.php b/src/Template/VanillaRenderer.php index 6b3e2eee..cd636c3c 100644 --- a/src/Template/VanillaRenderer.php +++ b/src/Template/VanillaRenderer.php @@ -5,12 +5,11 @@ /** * Renderer * - * A simple implementation of a template renderer. - * NOTE: To be removed in v1.0.0. Use "Template\Renderer" instead. + * NOTE: To be removed in v1.0.0. Use "Vanilla\Renderer" instead. * * @package Slytherin * @author Rougin Gutib */ -class VanillaRenderer extends Renderer +class VanillaRenderer extends Vanilla\Renderer { } diff --git a/tests/Application/ApplicationTestCases.php b/tests/Application/ApplicationTestCases.php index 4c35f651..c0fad39e 100644 --- a/tests/Application/ApplicationTestCases.php +++ b/tests/Application/ApplicationTestCases.php @@ -200,17 +200,6 @@ public function testHandleMethodWithServerRequest() */ public function testHandleMethodWithTypehintedParameter() { - $interface = 'Rougin\Slytherin\Routing\DispatcherInterface'; - - $dispatcher = $this->application->get($interface); - - // TODO: Implement resolving of type hinted parameters from container to PhrouteResolver ---------- - if (is_a($dispatcher, 'Rougin\Slytherin\Routing\PhrouteDispatcher')) - { - $this->markTestSkipped('Resolving type hinted parameters are not yet implemented in Phroute.'); - } - // ------------------------------------------------------------------------------------------------ - $request = $this->request('GET', '/typehint/202'); $expected = (integer) 202; diff --git a/tests/Debug/Vanilla/DebuggerTest.php b/tests/Debug/Vanilla/DebuggerTest.php index 4696667d..4a2eb7ac 100644 --- a/tests/Debug/Vanilla/DebuggerTest.php +++ b/tests/Debug/Vanilla/DebuggerTest.php @@ -2,16 +2,20 @@ namespace Rougin\Slytherin\Debug\Vanilla; +use Rougin\Slytherin\Debug\Vanilla\Debugger; +use Rougin\Slytherin\System; +use Rougin\Slytherin\Testcase; + /** * Debugger Test * * @package Slytherin * @author Rougin Gutib */ -class DebuggerTest extends \Rougin\Slytherin\Testcase +class DebuggerTest extends Testcase { /** - * @var \Rougin\Slytherin\Debug\DebuggerInterface + * @var \Rougin\Slytherin\Debug\Vanilla\Debugger */ protected $debugger; @@ -27,7 +31,7 @@ class DebuggerTest extends \Rougin\Slytherin\Testcase */ protected function doSetUp() { - $this->debugger = new \Rougin\Slytherin\Debug\Vanilla\Debugger; + $this->debugger = new Debugger; } /** @@ -39,7 +43,11 @@ public function testSetEnvironmentMethod() { $this->debugger->setEnvironment($this->environment); - $this->assertEquals($this->environment, $this->debugger->getEnvironment()); + $expected = $this->environment; + + $actual = $this->debugger->getEnvironment(); + + $this->assertEquals($expected, $actual); } /** @@ -49,18 +57,18 @@ public function testSetEnvironmentMethod() */ public function testDisplayMethod() { - $this->assertEquals('', $this->debugger->display()); + $this->debugger->display(); + + $this->assertEquals(error_reporting(), E_ALL); } /** - * Tests if the debugger is implemented in ErrorHandlerInterface. + * Tests if the debugger is implemented in DebuggerInterface. * * @return void */ public function testDebuggerInterface() { - $interface = 'Rougin\Slytherin\Debug\ErrorHandlerInterface'; - - $this->assertInstanceOf($interface, $this->debugger); + $this->assertInstanceOf(System::DEBUGGER, $this->debugger); } } diff --git a/tests/Debug/Whoops/DebuggerTest.php b/tests/Debug/Whoops/DebuggerTest.php index b0fe6598..7898ce70 100644 --- a/tests/Debug/Whoops/DebuggerTest.php +++ b/tests/Debug/Whoops/DebuggerTest.php @@ -2,16 +2,21 @@ namespace Rougin\Slytherin\Debug\Whoops; +use Rougin\Slytherin\Debug\Whoops\Debugger; +use Rougin\Slytherin\System; +use Rougin\Slytherin\Testcase; +use Whoops\Handler\PrettyPageHandler; + /** * Whoops Debugger Test * * @package Slytherin * @author Rougin Gutib */ -class DebuggerTest extends \Rougin\Slytherin\Testcase +class DebuggerTest extends Testcase { /** - * @var \Rougin\Slytherin\Debug\DebuggerInterface + * @var \Rougin\Slytherin\Debug\Whoops\Debugger */ protected $debugger; @@ -27,13 +32,12 @@ class DebuggerTest extends \Rougin\Slytherin\Testcase */ protected function doSetUp() { - if (! class_exists('Whoops\Run')) { + if (! class_exists('Whoops\Run')) + { $this->markTestSkipped('Whoops is not installed.'); } - $whoops = new \Whoops\Run; - - $this->debugger = new \Rougin\Slytherin\Debug\Whoops\Debugger($whoops); + $this->debugger = new Debugger(new \Whoops\Run); } /** @@ -45,7 +49,11 @@ public function testSetEnvironmentMethod() { $this->debugger->setEnvironment($this->environment); - $this->assertEquals($this->environment, $this->debugger->getEnvironment()); + $expected = $this->environment; + + $actual = $this->debugger->getEnvironment(); + + $this->assertEquals($expected, $actual); } /** @@ -55,11 +63,15 @@ public function testSetEnvironmentMethod() */ public function testSetHandlerMethod() { - $this->debugger->setHandler(new \Whoops\Handler\PrettyPageHandler); + $this->debugger->setHandler(new PrettyPageHandler); $handlers = $this->debugger->getHandlers(); - $this->assertInstanceOf('Whoops\Handler\PrettyPageHandler', $handlers[0]); + $expected = 'Whoops\Handler\PrettyPageHandler'; + + $actual = $handlers[0]; + + $this->assertInstanceOf($expected, $actual); } /** @@ -69,13 +81,17 @@ public function testSetHandlerMethod() */ public function testSetHandlerMethodWithCallback() { - $this->debugger->setHandler(function () { - return 'Hello'; - }); + $fn = function () { return 'Hello'; }; + + $this->debugger->setHandler($fn); $handlers = $this->debugger->getHandlers(); - $this->assertInstanceOf('Whoops\Handler\CallbackHandler', $handlers[0]); + $expected = 'Whoops\Handler\CallbackHandler'; + + $actual = $handlers[0]; + + $this->assertInstanceOf($expected, $actual); } /** @@ -85,18 +101,18 @@ public function testSetHandlerMethodWithCallback() */ public function testDisplayMethod() { - $this->assertInstanceOf('Whoops\Run', $this->debugger->display()); + $this->debugger->display(); + + $this->assertEquals(error_reporting(), E_ALL); } /** - * Tests if the debugger is implemented in ErrorHandlerInterface. + * Tests if the debugger is implemented in DebuggerInterface. * * @return void */ public function testDebuggerInterface() { - $interface = 'Rougin\Slytherin\Debug\ErrorHandlerInterface'; - - $this->assertInstanceOf($interface, $this->debugger); + $this->assertInstanceOf(System::DEBUGGER, $this->debugger); } } diff --git a/tests/Routing/FastRouteDispatcherTest.php b/tests/Routing/FastRouteDispatcherTest.php index 81362d9f..d16f7854 100644 --- a/tests/Routing/FastRouteDispatcherTest.php +++ b/tests/Routing/FastRouteDispatcherTest.php @@ -39,15 +39,16 @@ public function testDispatchMethodWithClassAndSlytherinRouter() $router->prefix('', 'Rougin\Slytherin\Fixture\Classes'); - $router->get('/', 'NewClass@index'); + $router->get('/hi/:name', function ($name) + { + return 'Hello ' . $name . '!'; + }); $dispatcher = new FastRouteDispatcher($router); - $controller = new NewClass; + $route = $dispatcher->dispatch('GET', '/hi/Slytherin'); - $route = $dispatcher->dispatch('GET', '/'); - - $expected = (string) $controller->index(); + $expected = (string) 'Hello Slytherin!'; $actual = $this->resolve($route); diff --git a/tests/Sample/Router.php b/tests/Sample/Router.php index 2c7cb123..6a9c6273 100644 --- a/tests/Sample/Router.php +++ b/tests/Sample/Router.php @@ -22,7 +22,7 @@ public function routes($parsed = false) $this->get('/response', 'Hello@response'); - $this->get('/hi/{name}', 'Hello@name'); + $this->get('/hi/:name', 'Hello@name'); $this->get('without-slash', 'Hello@string'); @@ -49,7 +49,7 @@ public function routes($parsed = false) return 'Welcome ' . $name . ', ' . $age . '!'; }); - $this->get('/call/{name}', function ($name) + $this->get('/call/:name', function ($name) { return 'Welcome ' . $name . '!'; });