PHPackages havokinspiration/wrench - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. havokinspiration/wrench ActiveCakephp-plugin[Utility & Helpers](/categories/utility) havokinspiration/wrench ======================= Maintenance mode plugin for CakePHP 3.X 3.1.0(7y ago)2661.2k↓36%6[1 issues](https://github.com/HavokInspiration/wrench/issues)MITPHPPHP >=5.6.0 Since Oct 18Pushed 7y ago6 watchersCompare [ Source](https://github.com/HavokInspiration/wrench)[ Packagist](https://packagist.org/packages/havokinspiration/wrench)[ RSS](/packages/havokinspiration-wrench/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (9)Dependencies (3)Versions (13)Used By (0) Wrench : CakePHP 3 Maintenance mode plugin ========================================== [](#wrench--cakephp-3-maintenance-mode-plugin) [![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.txt)[![Build Status](https://camo.githubusercontent.com/4c9babf4f3cb8de8d6ccfe9ffdd45ce841acc4fde83dd03dc2ac4ce704b9655d/68747470733a2f2f7472617669732d63692e6f72672f4861766f6b496e737069726174696f6e2f7772656e63682e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/HavokInspiration/wrench)[![codecov.io](https://camo.githubusercontent.com/790ffdf45e580bc136009a90b68f9a1cc056c32a5fe94470886706e865f6182f/68747470733a2f2f636f6465636f762e696f2f6769746875622f4861766f6b496e737069726174696f6e2f7772656e63682f636f7665726167652e7376673f6272616e63683d6d6173746572)](https://codecov.io/github/HavokInspiration/wrench?branch=master) Wrench is a CakePHP 3.X plugin that aims to provide an easy way to implement a **Maintenance Mode**for your CakePHP website / applications. Requirements ------------ [](#requirements) - PHP >= 5.5.9 - CakePHP >= 3.3.0 About the plugin versions ------------------------- [](#about-the-plugin-versions) CakePHP < 3.3.0CakePHP >= 3.3.0CakePHP >= 3.5.0Wrench 1.XWrench 2.XWrench 3.XPHP >= 5.4.16PHP >= 5.5.9PHP >= 5.6.0Uses CakePHP DispatcherFilter mecanismUses CakePHP Middleware Stack and PSR-7 Request / Response implementationUses CakePHP Middleware Stack and PSR-7 Request / Response implementation + no deprecation warning from CakePHP 3.6.XRecommanded package ------------------- [](#recommanded-package) If you want to create your own maintenance mode, you can use the [CakePHP 3 Bake plugin](https://github.com/cakephp/bake) Installation ------------ [](#installation) You can install this plugin into your CakePHP application using [composer](http://getcomposer.org). The recommended way to install composer packages is: ``` composer require havokinspiration/wrench ``` Loading the plugin ------------------ [](#loading-the-plugin) You can load the plugin using the shell command: ``` bin/cake plugin load Wrench ``` Or you can manually add the loading statement in the **boostrap.php** file of your application: ``` Plugin::load('Wrench'); ``` Usage ----- [](#usage) The plugin is built around a **Middleware** that will intercept the current request to return a customized response to warn the user that the website / app is undergoing maintenance. To use the Maintenance mode, you need to add the **MaintenanceMiddleware** to the **MiddlewareStack** in your Application file by adding the following elements : ``` use Wrench\Middleware\MaintenanceMiddleware; // ... public function middleware($middleware) { $middleware->add(new MaintenanceMiddleware()); // Other middleware configuration return $middleware; } ``` Since this Middleware is here to prevent the application from responding, it should be the first to be treated by the Dispatcher and should, as such, be configured as the first one, either by adding it in the beginning of the method with the `push()` method or using the `prepend()` method anywhere you want in your middlewares configuration. By default, only adding it with the previous line will make use of the **Redirect** mode. More informations on maintenance Modes below. The Middleware is only active when the Configure key `Wrench.enable` is equal to `true`. To enable the maintenance mode, use the following statement in your **bootstrap.php** file : ``` Configure::write('Wrench.enable', true); ``` ### Modes [](#modes) The plugin is built around the concept of "modes". Modes are special classes which will have the task of processing the request and return the proper response in order to warn the user that the website / application is undergoing maintenance. The plugin comes packaged with four maintenance modes : `Redirect`, `Output`, `Callback` and `View`. You can configure it to use specific modes when adding the Middleware to the Middleware stack by passing parameters to the Middleware constructor. The will result in a call looking like this : ``` $middleware->add(new MaintenanceMiddleware([ 'mode' => [ 'className' => 'Full\Namespace\To\Mode', 'config' => [ // Specific configuration parameters for the Mode ] ] ]); ``` If you need it, you can directly pass an instance of a `Mode` to the `mode` array key of the filter's config: ``` $middleware->add(new MaintenanceMiddleware([ 'mode' => new \Wrench\Mode\Redirect([ 'url' => 'http://example.com/maintenance' ]) ]); ``` #### IP Whitelisting [](#ip-whitelisting) While you put your application under maintenance, you might want, as the project administrator or developer, to be able to access the application. You can do so using the IP whitelisting feature. When configuring the `MaintenanceMiddleware`, just pass an array of allowed IP addresses to the `whitelist` key in the Middleware configuration array. All those IP will be allowed to access the application, even if the maintenance mode is on: ``` $middleware->add(new MaintenanceMiddleware([ 'whitelist' => ['1.2.3.4', '5.6.7.8'], ])); ``` In the above example, clients connecting with the IP address `1.2.3.4` or `5.6.7.8` will be able to access the project, even if the maintenance mode is on. #### Redirect Mode [](#redirect-mode) The Redirect Mode is the default one. It will perform a redirect to a specific URL. The Redirect Mode accepts the following parameters : - **url** : The URL where the redirect should point to. Default to the app base path pointing to a **maintenance.html**page. - **code** : The HTTP status code of the redirect response. The code should be in the 3XX range, otherwise, it might get overwritten. Default to 307. - **headers** : Array of additional headers to pass along the redirect response. Default to empty. You can customize all those parameters : ``` $middleware->add(new MaintenanceMiddleware([ 'mode' => [ 'className' => 'Wrench\Mode\Redirect', 'config' => [ 'url' => 'http://example.com/maintenance', 'code' => 303, 'headers' => ['someHeader' => 'someValue'] ] ] ]); ``` #### Output Mode [](#output-mode) The Output Mode allows you to display the content of a static file as a response for the maintenance status. It accepts multiple parameters : - **path** : the **absolute** path to the file that will be served. Default to {ROOT}/maintenance.html. - **code** : The HTTP status code of the redirect response. Default to 503. - **headers** : Array of additional headers to pass along the redirect response. Default to empty. You can customize all those parameters : ``` $middleware->add(new MaintenanceMiddleware([ 'mode' => [ 'className' => 'Wrench\Mode\Output', 'config' => [ 'path' => '/path/to/my/file', 'code' => 404, 'headers' => ['someHeader' => 'someValue'] ] ] ]); ``` #### Callback Mode [](#callback-mode) The Callback Mode gives you the ability to use a custom callable. It accepts only one parameter `callback` which should be a callable. The callable will take two arguments : - **request** : A `\Psr\Http\Message\ServerRequestInterface` instance - **response** : A `\Psr\Http\Message\ResponseInterface` instance The callable is expected to return a `\Psr\Http\Message\ResponseInterface` if the request is to be stopped. ``` $middleware->add(new MaintenanceMiddleware([ 'mode' => [ 'className' => 'Wrench\Mode\Callback', 'config' => [ 'callback' => function($request, $response) { $string = 'Some content from a callback'; $stream = new Stream(fopen('php://memory', 'r+')); $stream->write($string); $response = $response->withBody($stream); $response = $response->withStatus(503); $response = $response->withHeader('someHeader', 'someValue'); return $response; } ] ] ]); ``` #### View Mode [](#view-mode) The View Mode gives you the ability to use a View to render the maintenance page. This gives you the ability to leverage helpers and the layout / template system of the framework. It accepts multiple parameters : - **code** : The HTTP status code of the redirect response. Default to 503. - **headers** : Array of additional headers to pass along the redirect response. Default to empty. - **view** : Array of parameters to pass to the View class constructor. Only the following options are supported : - **className** : Fully qualified class name of the View class to use. Default to AppView - **templatePath** : Path to the template you wish to display (relative to your `src/Template` directory). You can use plugin dot notation. - **template** : Template name to use. Default to "maintenance". - **plugin** : Theme where to find the layout and template - **theme** : Same thing than plugin - **layout** : Layout name to use. Default to "default" - **layoutPath** : Path to the layout you wish to display (relative to your `src/Template` directory). You can use plugin dot notation. Default to "Layout" ``` // Will load a template ``src/Template/Maintenance/maintenance.ctp`` // in a layout ``src/Template/Layout/Maintenance/maintenance.ctp`` $middleware->add(new MaintenanceMiddleware([ 'mode' => [ 'className' => 'Wrench\Mode\View', 'config' => [ 'view' => [ 'templatePath' => 'Maintenance', 'layout' => 'maintenance', 'layoutPath' => 'Maintenance' ] ] ] ]); ``` ### Creating a custom mode [](#creating-a-custom-mode) If you have special needs, you can create your own maintenance mode. To get started quickly, you can use the `bake` console tool to generate a skeleton: ``` bin/cake bake maintenance_mode MyCustomMode ``` This will generate a `MyCustomMode` class file under the `App\Maintenance\Mode` namespace (as well as a test file). Your skeleton will only contain one method `process()` returning a `\Psr\Http\Message\ResponseInterface` object. This is where the logic of your maintenance mode goes. You can either make the method return a `ResponseInterface` object which will shortcut the request cycle and use the returned `ResponseInterface` object to respond to the request. Any other returned value will make the maintenance mode no-op and the request cycle will go on. This is useful if you need to display the maintenance status only on specific conditions. The Mode implements the `InstanceConfigTrait` which allows you to easily define default configuration parameters and gives you easy access to them. Keep in mind that the `ResponseInterface` you need to return is PSR-7 compliant. You can get more details about the implementation and how to interact with it on [the PHP-FIG website](http://www.php-fig.org/psr/psr-7/)as well as [on the CakePHP documentation](https://github.com/cakephp/docs/blob/3.3/en/controllers/middleware.rst#psr7-requests-and-responses) You can check out the implemented modes to have some examples. ### Conditionally applying the maintenance mode [](#conditionally-applying-the-maintenance-mode) Conditionally applying a middleware is currently not possible with the current implementation of the Middleware stack in CakePHP 3.3. A documentation on how to do this will be added when and if this feature is implemented in the core. Contributing ------------ [](#contributing) If you find a bug or would like to ask for a feature, please use the [GitHub issue tracker](https://github.com/HavokInspiration/wrench/issues). If you would like to submit a fix or a feature, please fork the repository and [submit a pull request](https://github.com/HavokInspiration/wrench/pulls). ### Coding standards [](#coding-standards) Since this plugin is tangled with features from the CakePHP Core and to provide consistency, it follows the [CakePHP coding standards](http://book.cakephp.org/3.0/en/contributing/cakephp-coding-conventions.html). When submitting a pull request, make sure your code follows these standards. You can check it by installing the code sniffer : ``` composer require cakephp/cakephp-codesniffer:dev-master ``` And then running the sniff : ``` ./vendor/bin/phpcs -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP ./src ./tests ``` License ------- [](#license) Copyright (c) 2015 - 2017, Yves Piquel and licensed under [The MIT License](http://opensource.org/licenses/mit-license.php). Please refer to the LICENSE.txt file. ### Health Score 39 — LowBetter than 86% of packages Maintenance19 Infrequent updates — may be unmaintained Popularity41 Moderate usage in the ecosystem Community17 Small or concentrated contributor base Maturity65 Established project with proven stability Bus Factor1 Top contributor holds 87.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~88 days Recently: every ~62 days Total 12 Last Release 2899d ago Major Versions 0.2 → 1.0.02015-11-18 1.0.2 → 2.0.02016-09-25 2.x-dev → 3.0.02018-04-23 PHP version history (3 changes)0.1PHP >=5.4.16 2.0.0PHP >=5.5.9 3.0.0PHP >=5.6.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/c7ade5318f46ea6ffa30a140639a71bb9f078f8322efc24268d0f94cd7c4deee?d=identicon)[HavokInspiration](/maintainers/HavokInspiration) --- Top Contributors [![HavokInspiration](https://avatars.githubusercontent.com/u/5243386?v=4)](https://github.com/HavokInspiration "HavokInspiration (93 commits)")[![cercos](https://avatars.githubusercontent.com/u/1372688?v=4)](https://github.com/cercos "cercos (6 commits)")[![ludeus](https://avatars.githubusercontent.com/u/7382872?v=4)](https://github.com/ludeus "ludeus (5 commits)")[![ADmad](https://avatars.githubusercontent.com/u/142658?v=4)](https://github.com/ADmad "ADmad (2 commits)") --- Tags cakephpmaintenance-modemiddleware ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/havokinspiration-wrench/health.svg) ``` [![Health](https://phpackages.com/badges/havokinspiration-wrench/health.svg)](https://phpackages.com/packages/havokinspiration-wrench) ``` ### Alternatives [dereuromark/cakephp-tools A CakePHP plugin containing lots of useful and reusable tools 338920.1k32](/packages/dereuromark-cakephp-tools)[markstory/asset_compress An asset compression plugin for CakePHP. Provides file concatenation and a flexible filter system for preprocessing and minification. 3761.0M11](/packages/markstory-asset-compress)[dereuromark/cakephp-shim A CakePHP plugin to shim applications between major framework versions. 401.0M11](/packages/dereuromark-cakephp-shim)[cakedc/cakephp-phpstan CakePHP plugin extension for PHPStan. 40676.6k31](/packages/cakedc-cakephp-phpstan)[dereuromark/cakephp-dto A CakePHP plugin for generating immutable Data Transfer Objects with full type safety 2988.9k3](/packages/dereuromark-cakephp-dto)[dereuromark/cakephp-geo A CakePHP plugin around geocoding tools and helpers. 51174.9k4](/packages/dereuromark-cakephp-geo) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)