diff --git a/.gitattributes b/.gitattributes index 19bebf6a..5d72b06d 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,11 +1,11 @@ -/doc export-ignore -/test export-ignore /.coveralls.yml export-ignore /.docheader export-ignore /.gitattributes export-ignore /.gitignore export-ignore /.travis.yml export-ignore /composer.lock export-ignore +/docs/ export-ignore /mkdocs.yml export-ignore /phpcs.xml export-ignore /phpunit.xml.dist export-ignore +/test/ export-ignore diff --git a/.gitignore b/.gitignore index 58cb57e7..245087af 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ -doc/html/ -vendor/ -phpunit.xml -zf-mkdoc-theme/ -clover.xml -coveralls-upload.json -zf-mkdoc-theme.tgz +/clover.xml +/coveralls-upload.json +/docs/html/ +/phpunit.xml +/vendor/ +/zf-mkdoc-theme.tgz +/zf-mkdoc-theme/ diff --git a/.travis.yml b/.travis.yml index 0eea7cd4..7f8e7a4e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -10,7 +10,6 @@ env: global: - COMPOSER_ARGS="--no-interaction" - COVERAGE_DEPS="satooshi/php-coveralls" - - LEGACY_DEPS="phpunit/phpunit" matrix: include: @@ -20,8 +19,7 @@ matrix: - php: 5.6 env: - DEPS=locked - - CS_CHECK=true - - TEST_COVERAGE=true + - LEGACY_DEPS="phpunit/phpunit" - php: 5.6 env: - DEPS=latest @@ -31,6 +29,7 @@ matrix: - php: 7 env: - DEPS=locked + - LEGACY_DEPS="phpunit/phpunit" - php: 7 env: - DEPS=latest @@ -40,6 +39,8 @@ matrix: - php: 7.1 env: - DEPS=locked + - CS_CHECK=true + - TEST_COVERAGE=true - php: 7.1 env: - DEPS=latest @@ -52,16 +53,13 @@ matrix: - php: 7.2 env: - DEPS=latest - allow_failures: - - php: 7.2 before_install: - - if [[ $TEST_COVERAGE != 'true' && "$(php --version | grep xdebug -ci)" -ge 1 ]]; then phpenv config-rm xdebug.ini || return 0 ; fi - - travis_retry composer self-update + - if [[ $TEST_COVERAGE != 'true' ]]; then phpenv config-rm xdebug.ini || return 0 ; fi install: - travis_retry composer install $COMPOSER_ARGS --ignore-platform-reqs - - if [[ $TRAVIS_PHP_VERSION =~ ^5.6 ]]; then travis_retry composer update $COMPOSER_ARGS --with-dependencies $LEGACY_DEPS ; fi + - if [[ $LEGACY_DEPS != '' ]]; then travis_retry composer update $COMPOSER_ARGS --with-dependencies $LEGACY_DEPS ; fi - if [[ $DEPS == 'latest' ]]; then travis_retry composer update $COMPOSER_ARGS ; fi - if [[ $DEPS == 'lowest' ]]; then travis_retry composer update --prefer-lowest --prefer-stable $COMPOSER_ARGS ; fi - if [[ $TEST_COVERAGE == 'true' ]]; then travis_retry composer require --dev $COMPOSER_ARGS $COVERAGE_DEPS ; fi diff --git a/LICENSE.md b/LICENSE.md index c7e9a85d..82cd6c76 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,12 +1,27 @@ -Copyright (c) 2015-2016, Zend Technologies USA, Inc. +Copyright (c) 2015-2017, Zend Technologies USA, Inc. All rights reserved. -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: -- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. +- Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. -- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. +- Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. -- Neither the name of Zend Technologies USA, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. +- Neither the name of Zend Technologies USA, Inc. nor the names of its + contributors may be used to endorse or promote products derived from this + software without specific prior written permission. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md index 7a280938..bce397a4 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ documentation. ## Documentation -Documentation is [in the doc tree](doc/book/), and can be compiled using [mkdocs](http://www.mkdocs.org): +Documentation is [in the doc tree](docs/book/), and can be compiled using [mkdocs](http://www.mkdocs.org): ```bash $ mkdocs build diff --git a/composer.json b/composer.json index f40c8d6a..b7c32a4f 100644 --- a/composer.json +++ b/composer.json @@ -1,32 +1,25 @@ { "name": "zendframework/zend-expressive", "description": "PSR-7 Middleware Microframework based on Stratigility", - "homepage": "https://docs.zendframework.com/zend-expressive/", - "type": "library", "license": "BSD-3-Clause", "keywords": [ "http", "middleware", "psr", "psr-7", - "psr-11" + "psr-11", + "zf", + "zendframework", + "zend-expressive" ], "support": { "docs": "https://docs.zendframework.com/zend-expressive/", "issues": "https://github.com/zendframework/zend-expressive/issues", "source": "https://github.com/zendframework/zend-expressive", + "rss": "https://github.com/zendframework/zend-expressive/releases.atom", "slack": "https://zendframework-slack.herokuapp.com", "forum": "https://discourse.zendframework.com/c/questions/expressive" }, - "extra": { - "branch-alias": { - "dev-master": "2.0-dev", - "dev-develop": "2.1-dev" - } - }, - "config": { - "sort-packages": true - }, "require": { "php": "^5.6 || ^7.0", "fig/http-message-util": "^1.1.2", @@ -43,7 +36,7 @@ "filp/whoops": "^2.1.6 || ^1.1.10", "malukenho/docheader": "^0.1.5", "mockery/mockery": "^1.0", - "phpunit/phpunit": "^5.7.22 || ^6.4.1", + "phpunit/phpunit": "^5.7.23 || ^6.4.3", "zendframework/zend-coding-standard": "~1.0.0", "zendframework/zend-expressive-aurarouter": "^2.0", "zendframework/zend-expressive-fastroute": "^2.0", @@ -53,6 +46,14 @@ "conflict": { "container-interop/container-interop": "<1.2.0" }, + "suggest": { + "filp/whoops": "^2.1 to use the Whoops error handler", + "zendframework/zend-expressive-helpers": "^3.0 for its UrlHelper, ServerUrlHelper, and BodyParseMiddleware", + "aura/di": "^3.2 to make use of Aura.Di dependency injection container", + "xtreamwayz/pimple-container-interop": "^1.0 to use Pimple for dependency injection", + "zendframework/zend-expressive-tooling": "For migration and development tools; require it with the --dev flag", + "zendframework/zend-servicemanager": "^3.3 to use zend-servicemanager for dependency injection" + }, "autoload": { "psr-4": { "Zend\\Expressive\\": "src/" @@ -66,13 +67,14 @@ "test/class_exists.php" ] }, - "suggest": { - "filp/whoops": "^2.1 to use the Whoops error handler", - "zendframework/zend-expressive-helpers": "^3.0 for its UrlHelper, ServerUrlHelper, and BodyParseMiddleware", - "aura/di": "^3.2 to make use of Aura.Di dependency injection container", - "xtreamwayz/pimple-container-interop": "^1.0 to use Pimple for dependency injection", - "zendframework/zend-expressive-tooling": "For migration and development tools; require it with the --dev flag", - "zendframework/zend-servicemanager": "^3.3 to use zend-servicemanager for dependency injection" + "config": { + "sort-packages": true + }, + "extra": { + "branch-alias": { + "dev-master": "2.0-dev", + "dev-develop": "2.1-dev" + } }, "bin": [ "bin/expressive-tooling" @@ -83,11 +85,11 @@ "@cs-check", "@test" ], - "upload-coverage": "coveralls -v", "cs-check": "phpcs", "cs-fix": "phpcbf", "test": "phpunit --colors=always", - "test-coverage": "phpunit --coverage-clover clover.xml", - "license-check": "vendor/bin/docheader check src/ test/" + "test-coverage": "phpunit --colors=always --coverage-clover clover.xml", + "upload-coverage": "coveralls -v", + "license-check": "docheader check src/ test/" } } diff --git a/composer.lock b/composer.lock index 7d7e352d..03b6e6ed 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file", "This file is @generated automatically" ], - "content-hash": "b72598edd15c6e040534eafb4d114a43", + "content-hash": "9062dbff015d1be5f3da3fac93304d8c", "packages": [ { "name": "fig/http-message-util", @@ -865,37 +865,40 @@ }, { "name": "myclabs/deep-copy", - "version": "1.6.1", + "version": "1.7.0", "source": { "type": "git", "url": "https://github.com/myclabs/DeepCopy.git", - "reference": "8e6e04167378abf1ddb4d3522d8755c5fd90d102" + "reference": "3b8a3a99ba1f6a3952ac2747d989303cbd6b7a3e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/myclabs/DeepCopy/zipball/8e6e04167378abf1ddb4d3522d8755c5fd90d102", - "reference": "8e6e04167378abf1ddb4d3522d8755c5fd90d102", + "url": "https://api.github.com/repos/myclabs/DeepCopy/zipball/3b8a3a99ba1f6a3952ac2747d989303cbd6b7a3e", + "reference": "3b8a3a99ba1f6a3952ac2747d989303cbd6b7a3e", "shasum": "" }, "require": { - "php": ">=5.4.0" + "php": "^5.6 || ^7.0" }, "require-dev": { - "doctrine/collections": "1.*", - "phpunit/phpunit": "~4.1" + "doctrine/collections": "^1.0", + "doctrine/common": "^2.6", + "phpunit/phpunit": "^4.1" }, "type": "library", "autoload": { "psr-4": { "DeepCopy\\": "src/DeepCopy/" - } + }, + "files": [ + "src/DeepCopy/deep_copy.php" + ] }, "notification-url": "https://packagist.org/downloads/", "license": [ "MIT" ], "description": "Create deep copies (clones) of your objects", - "homepage": "https://github.com/myclabs/DeepCopy", "keywords": [ "clone", "copy", @@ -903,7 +906,7 @@ "object", "object graph" ], - "time": "2017-04-12T18:52:22+00:00" + "time": "2017-10-19T19:58:43+00:00" }, { "name": "nikic/fast-route", @@ -1511,16 +1514,16 @@ }, { "name": "phpunit/phpunit", - "version": "6.4.1", + "version": "6.4.3", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "b770d8ba7e60295ee91d69d5a5e01ae833cac220" + "reference": "06b28548fd2b4a20c3cd6e247dc86331a7d4db13" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/b770d8ba7e60295ee91d69d5a5e01ae833cac220", - "reference": "b770d8ba7e60295ee91d69d5a5e01ae833cac220", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/06b28548fd2b4a20c3cd6e247dc86331a7d4db13", + "reference": "06b28548fd2b4a20c3cd6e247dc86331a7d4db13", "shasum": "" }, "require": { @@ -1591,7 +1594,7 @@ "testing", "xunit" ], - "time": "2017-10-07T17:53:53+00:00" + "time": "2017-10-16T13:18:59+00:00" }, { "name": "phpunit/phpunit-mock-objects", @@ -1746,30 +1749,30 @@ }, { "name": "sebastian/comparator", - "version": "2.0.2", + "version": "2.1.0", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/comparator.git", - "reference": "ae068fede81d06e7bb9bb46a367210a3d3e1fe6a" + "reference": "1174d9018191e93cb9d719edec01257fc05f8158" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/ae068fede81d06e7bb9bb46a367210a3d3e1fe6a", - "reference": "ae068fede81d06e7bb9bb46a367210a3d3e1fe6a", + "url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/1174d9018191e93cb9d719edec01257fc05f8158", + "reference": "1174d9018191e93cb9d719edec01257fc05f8158", "shasum": "" }, "require": { "php": "^7.0", "sebastian/diff": "^2.0", - "sebastian/exporter": "^3.0" + "sebastian/exporter": "^3.1" }, "require-dev": { - "phpunit/phpunit": "^6.0" + "phpunit/phpunit": "^6.4" }, "type": "library", "extra": { "branch-alias": { - "dev-master": "2.0.x-dev" + "dev-master": "2.1.x-dev" } }, "autoload": { @@ -1800,13 +1803,13 @@ } ], "description": "Provides the functionality to compare PHP values for equality", - "homepage": "http://www.github.com/sebastianbergmann/comparator", + "homepage": "https://github.com/sebastianbergmann/comparator", "keywords": [ "comparator", "compare", "equality" ], - "time": "2017-08-03T07:14:59+00:00" + "time": "2017-11-03T07:16:52+00:00" }, { "name": "sebastian/diff", diff --git a/CONDUCT.md b/docs/CODE_OF_CONDUCT.md similarity index 96% rename from CONDUCT.md rename to docs/CODE_OF_CONDUCT.md index c663d2be..02fafcd1 100644 --- a/CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -1,6 +1,6 @@ # Contributor Code of Conduct -The Zend Framework project adheres to [The Code Manifesto](http://codemanifesto.com) +This project adheres to [The Code Manifesto](http://codemanifesto.com) as its guidelines for contributor interactions. ## The Code Manifesto diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 67% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md index c89901da..5656e0c5 100644 --- a/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,37 +2,16 @@ ## RESOURCES -If you wish to contribute to Zend Framework, please be sure to +If you wish to contribute to this project, please be sure to read/subscribe to the following resources: - - [Coding Standards](https://github.com/zendframework/zf2/wiki/Coding-Standards) - - [Contributor's Guide](CONTRIBUTING.md) - - ZF Contributor's mailing list: - Archives: http://zend-framework-community.634137.n4.nabble.com/ZF-Contributor-f680267.html - Subscribe: zf-contributors-subscribe@lists.zend.com - - ZF Contributor's IRC channel: - #zftalk.dev on Freenode.net + - [Coding Standards](https://github.com/zendframework/zend-coding-standard) + - [Forums](https://discourse.zendframework.com/c/contributors) + - [Slack](https://zendframework-slack.herokuapp.com) + - [Code of Conduct](CODE_OF_CONDUCT.md) -If you are working on new features or refactoring [create a proposal](https://github.com/zendframework/zend-expressive/issues/new). - -## Reporting Potential Security Issues - -If you have encountered a potential security vulnerability, please **DO NOT** report it on the public -issue tracker: send it to us at [zf-security@zend.com](mailto:zf-security@zend.com) instead. -We will work with you to verify the vulnerability and patch it as soon as possible. - -When reporting issues, please provide the following information: - -- Component(s) affected -- A description indicating how to reproduce the issue -- A summary of the security vulnerability and impact - -We request that you contact us via the email address above and give the project -contributors a chance to resolve the vulnerability and issue a new release prior -to any public exposure; this helps protect users and provides them with a chance -to upgrade and/or update in order to protect their applications. - -For sensitive email communications, please use [our PGP key](http://framework.zend.com/zf-security-pgp-key.asc). +If you are working on new features or refactoring +[create a proposal](https://github.com/zendframework/zend-expressive/issues/new). ## RUNNING TESTS @@ -86,18 +65,6 @@ $ composer cs-fix If the above fixes any CS issues, please re-run the tests to ensure they pass, and make sure you add and commit the changes after verification. -## Running License Checks - -File-level docblocks should follow the format demonstrated in `.docheader`. To -check for conformity, use: - -```console -$ composer license-check -``` - -This will flag files that are incorrect, which you can then update. Re-run the -tool to verify your changes. - ## Recommended Workflow for Contributions Your first step is to establish a public repository from which we can @@ -189,15 +156,7 @@ To send a pull request, you have two options. If using GitHub, you can do the pull request from there. Navigate to your repository, select the branch you just created, and then select the "Pull Request" button in the upper right. Select the user/organization -"zendframework" as the recipient. - -If using your own repository - or even if using GitHub - you can use `git -format-patch` to create a patchset for us to apply; in fact, this is -**recommended** for security-related patches. If you use `format-patch`, please -send the patches as attachments to: - -- zf-devteam@zend.com for patches without security implications -- zf-security@zend.com for security patches +"zendframework" (or whatever the upstream organization is) as the recipient. #### What branch to issue the pull request against? @@ -228,7 +187,3 @@ repository, we suggest doing some cleanup of these branches. ```console $ git push {username} : ``` - -## Conduct - -Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project. diff --git a/docs/ISSUE_TEMPLATE.md b/docs/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..e18df9c5 --- /dev/null +++ b/docs/ISSUE_TEMPLATE.md @@ -0,0 +1,19 @@ + - [ ] I was not able to find an [open](https://github.com/zendframework/zend-expressive/issues?q=is%3Aopen) or [closed](https://github.com/zendframework/zend-expressive/issues?q=is%3Aclosed) issue matching what I'm seeing. + - [ ] This is not a question. (Questions should be asked on [slack](https://zendframework.slack.com/) ([Signup for Slack here](https://zendframework-slack.herokuapp.com/)) or our [forums](https://discourse.zendframework.com/).) + +Provide a narrative description of what you are trying to accomplish. + +### Code to reproduce the issue + + + +```php +``` + +### Expected results + + + +### Actual results + + diff --git a/docs/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..f00d90c0 --- /dev/null +++ b/docs/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,25 @@ +Provide a narrative description of what you are trying to accomplish: + +- [ ] Are you fixing a bug? + - [ ] Detail how the bug is invoked currently. + - [ ] Detail the original, incorrect behavior. + - [ ] Detail the new, expected behavior. + - [ ] Base your feature on the `master` branch, and submit against that branch. + - [ ] Add a regression test that demonstrates the bug, and proves the fix. + - [ ] Add a `CHANGELOG.md` entry for the fix. + +- [ ] Are you creating a new feature? + - [ ] Why is the new feature needed? What purpose does it serve? + - [ ] How will users use the new feature? + - [ ] Base your feature on the `develop` branch, and submit against that branch. + - [ ] Add only one feature per pull request; split multiple features over multiple pull requests + - [ ] Add tests for the new feature. + - [ ] Add documentation for the new feature. + - [ ] Add a `CHANGELOG.md` entry for the new feature. + +- [ ] Is this related to quality assurance? + + +- [ ] Is this related to documentation? + + diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md new file mode 100644 index 00000000..6b5d93b8 --- /dev/null +++ b/docs/SUPPORT.md @@ -0,0 +1,25 @@ +# Getting Support + +Zend Framework offers three support channels: + +- For real-time questions, use our + [Slack](https://zendframework-slack.herokuapp.com) +- For detailed questions (e.g., those requiring examples) use our + [forums](https://discourse.zendframework.com/c/questions/expressive) +- To report issues, use this repository's + [issue tracker](https://github.com/zendframework/zend-expressive/issues/new) + +**DO NOT** use the issue tracker to ask questions; use Slack or the forums for +that. Questions posed to the issue tracker will be closed. + +When reporting an issue, please include the following details: + +- A narrative description of what you are trying to accomplish. +- The minimum code necessary to reproduce the issue. +- The expected results of exercising that code. +- The actual results received. + +We may ask for additional details: what version of the library you are using, +and what PHP version was used to reproduce the issue. + +You may also submit a failing test case as a pull request. diff --git a/doc/book/cookbook/autowiring-routes-and-pipelines.md b/docs/book/cookbook/autowiring-routes-and-pipelines.md similarity index 100% rename from doc/book/cookbook/autowiring-routes-and-pipelines.md rename to docs/book/cookbook/autowiring-routes-and-pipelines.md diff --git a/doc/book/cookbook/common-prefix-for-routes.md b/docs/book/cookbook/common-prefix-for-routes.md similarity index 100% rename from doc/book/cookbook/common-prefix-for-routes.md rename to docs/book/cookbook/common-prefix-for-routes.md diff --git a/doc/book/cookbook/custom-404-page-handling.md b/docs/book/cookbook/custom-404-page-handling.md similarity index 100% rename from doc/book/cookbook/custom-404-page-handling.md rename to docs/book/cookbook/custom-404-page-handling.md diff --git a/doc/book/cookbook/debug-toolbars.md b/docs/book/cookbook/debug-toolbars.md similarity index 100% rename from doc/book/cookbook/debug-toolbars.md rename to docs/book/cookbook/debug-toolbars.md diff --git a/doc/book/cookbook/flash-messengers.md b/docs/book/cookbook/flash-messengers.md similarity index 99% rename from doc/book/cookbook/flash-messengers.md rename to docs/book/cookbook/flash-messengers.md index 94fd32e7..58d9e3d8 100644 --- a/doc/book/cookbook/flash-messengers.md +++ b/docs/book/cookbook/flash-messengers.md @@ -22,7 +22,7 @@ damess/expressive-session-middleware. ## slim/flash -Slim's [Flash messages service provider](https://github.com/slimphp/Slim-Flash) can be +Slim's [Flash messages service provider](https://github.com/slimphp/Slim-Flash) can be used in Expressive. It uses PHP's native session support. First, you'll need to add it to your application: @@ -261,6 +261,6 @@ function($request, DelegateInterface $delegate) ->getFlash('message'); // ... } -``` +``` From there, it's a matter of providing the flash messages to your template. diff --git a/doc/book/cookbook/modular-layout.md b/docs/book/cookbook/modular-layout.md similarity index 98% rename from doc/book/cookbook/modular-layout.md rename to docs/book/cookbook/modular-layout.md index ddc37b21..3e55692b 100644 --- a/doc/book/cookbook/modular-layout.md +++ b/docs/book/cookbook/modular-layout.md @@ -10,13 +10,13 @@ Zend Framework 2 applications have a concept of modules, independent units that can provide configuration, services, and hooks into its MVC lifecycle. This functionality is provided by zend-modulemanager. - + While zend-modulemanager could be used with Expressive, we suggest another approach: modules that are based only on configuration. This powerful approach doesn't affect performance, and offers extensive flexibility: each module can -provide its own services (with factories), default configuration, and routes. +provide its own services (with factories), default configuration, and routes. -This cookbook will show how to organize modules using +This cookbook will show how to organize modules using [mtymek/expressive-config-manager](https://github.com/mtymek/expressive-config-manager), a lightweight library that aggregates and merges configuration, optionally caching it. @@ -32,7 +32,7 @@ $ composer require mtymek/expressive-config-manager The default Expressive skeleton installs a `config/config.php` file, which aggregates all configuration. When using the configuration manager, you will -need to replace the contents of that file with the following code: +need to replace the contents of that file with the following code: ```php 'bar', + 'foo' => 'bar', ]; - + // Step 2: Inject data into the request, call the next middleware and wait for the response $response = $delegate->process($request->withAttribute(self::class, $data)); - + // Step 3: Optionally, do something (with the response) before returning the response - + // Step 4: Return the response return $response; } @@ -59,12 +59,12 @@ class ReceivingDataMiddleware implements MiddlewareInterface { // Step 1: Grab the data from the request and use it $data = $request->getAttribute(PassingDataMiddleware::class); - + // Step 2: Call the next middleware and wait for the response $response = $delegate->process($request); - + // Step 3: Optionally, do something (with the response) before returning the response - + // Step 4: Return the response return $response; } @@ -86,15 +86,15 @@ use Zend\Diactoros\Response\HtmlResponse; class ExampleAction implements MiddlewareInterface { // ... - + public function process(ServerRequestInterface $request, DelegateInterface $delegate) { // Step 1: Grab the data from the request $data = $request->getAttribute(PassingDataMiddleware::class); $id = $request->getAttribute('id'); - + // Step 2: Do some more stuff - + // Step 3: Return a Response return new HtmlResponse( $this->templateRenderer->render('blog::entry', [ diff --git a/doc/book/cookbook/route-specific-pipeline.md b/docs/book/cookbook/route-specific-pipeline.md similarity index 100% rename from doc/book/cookbook/route-specific-pipeline.md rename to docs/book/cookbook/route-specific-pipeline.md diff --git a/doc/book/cookbook/setting-locale-depending-routing-parameter.md b/docs/book/cookbook/setting-locale-depending-routing-parameter.md similarity index 99% rename from doc/book/cookbook/setting-locale-depending-routing-parameter.md rename to docs/book/cookbook/setting-locale-depending-routing-parameter.md index 758b577d..1cc04845 100644 --- a/doc/book/cookbook/setting-locale-depending-routing-parameter.md +++ b/docs/book/cookbook/setting-locale-depending-routing-parameter.md @@ -199,7 +199,7 @@ $app->pipe(LocalizationMiddleware::class); /* ... */ ``` -If using a configuration-driven application, register it within your +If using a configuration-driven application, register it within your `config/autoload/middleware-pipeline.global.php` file, injecting it into the pipeline following the routing middleware: diff --git a/doc/book/cookbook/setting-locale-without-routing-parameter.md b/docs/book/cookbook/setting-locale-without-routing-parameter.md similarity index 98% rename from doc/book/cookbook/setting-locale-without-routing-parameter.md rename to docs/book/cookbook/setting-locale-without-routing-parameter.md index 3c3c4a5e..82db8d38 100644 --- a/doc/book/cookbook/setting-locale-without-routing-parameter.md +++ b/docs/book/cookbook/setting-locale-without-routing-parameter.md @@ -38,27 +38,27 @@ use Zend\Expressive\Helper\UrlHelper; class SetLocaleMiddleware implements MiddlewareInterface { private $helper; - + public function __construct(UrlHelper $helper) { $this->helper = $helper; } - + public function process(ServerRequestInterface $request, DelegateInterface $delegate) { $uri = $request->getUri(); - + $path = $uri->getPath(); - + if (! preg_match('#^/(?P[a-z]{2,3}([-_][a-zA-Z]{2}|))/#', $path, $matches)) { Locale::setDefault('de_DE'); return $delegate->process($request); } - + $locale = $matches['locale']; Locale::setDefault(Locale::canonicalize($locale)); $this->helper->setBasePath($locale); - + return $delegate->process($request->withUri( $uri->withPath(substr($path, 3)) )); @@ -156,8 +156,8 @@ return [ ## Url generation in the view -Since the `UrlHelper` has the locale set as a base path, you don't need -to worry about generating URLs within your view. Just use the helper to +Since the `UrlHelper` has the locale set as a base path, you don't need +to worry about generating URLs within your view. Just use the helper to generate a URL and it will do the rest. ```php @@ -171,8 +171,8 @@ generate a URL and it will do the rest. ## Redirecting within your middleware -If you want to add the locale parameter when creating URIs within your -action middleware, you just need to inject the `UrlHelper` into your +If you want to add the locale parameter when creating URIs within your +action middleware, you just need to inject the `UrlHelper` into your middleware and use it for URL generation: ```php @@ -188,12 +188,12 @@ use Zend\Expressive\Helper\UrlHelper; class RedirectAction implements MiddlewareInterface { private $helper; - + public function __construct(UrlHelper $helper) { $this->helper = $helper; } - + /** * @param ServerRequestInterface $request * @param DelegateInterface $delegate diff --git a/doc/book/cookbook/using-a-base-path.md b/docs/book/cookbook/using-a-base-path.md similarity index 98% rename from doc/book/cookbook/using-a-base-path.md rename to docs/book/cookbook/using-a-base-path.md index ac122101..2b5a2647 100644 --- a/doc/book/cookbook/using-a-base-path.md +++ b/docs/book/cookbook/using-a-base-path.md @@ -130,7 +130,7 @@ the request URI and the operating system path to the application. The primary advantage of `mtymek/blast-base-url` is in its additional features: -- it injects `Zend\Expressive\Helper\UrlHelper` with the base path, allowing you +- it injects `Zend\Expressive\Helper\UrlHelper` with the base path, allowing you to create relative route-based URLs. - it provides a new helper, `Blast\BaseUrl\BasePathHelper`, which allows you to create URLs relative to the base path; this is particularly useful for assets. @@ -142,7 +142,7 @@ To enable these features, we'll add some configuration to return [ 'dependencies' => [ 'invokables' => [ - Blast\BaseUrl\BasePathHelper::class => Blast\BaseUrl\BasePathHelper::class, + Blast\BaseUrl\BasePathHelper::class => Blast\BaseUrl\BasePathHelper::class, /* ... */ ], ], diff --git a/doc/book/cookbook/using-custom-view-helpers.md b/docs/book/cookbook/using-custom-view-helpers.md similarity index 100% rename from doc/book/cookbook/using-custom-view-helpers.md rename to docs/book/cookbook/using-custom-view-helpers.md diff --git a/doc/book/cookbook/using-routed-middleware-class-as-controller.md b/docs/book/cookbook/using-routed-middleware-class-as-controller.md similarity index 98% rename from doc/book/cookbook/using-routed-middleware-class-as-controller.md rename to docs/book/cookbook/using-routed-middleware-class-as-controller.md index 3ff01bf8..ea479913 100644 --- a/doc/book/cookbook/using-routed-middleware-class-as-controller.md +++ b/docs/book/cookbook/using-routed-middleware-class-as-controller.md @@ -73,7 +73,7 @@ use Zend\Expressive\Template\TemplateRendererInterface; class AlbumPage implements MiddlewareInterface { - private $template; + private $template; public function __construct(TemplateRendererInterface $template) { @@ -170,7 +170,7 @@ use Zend\Expressive\Template\TemplateRendererInterface; class AlbumPage extends AbstractPage { - private $template; + private $template; public function __construct(TemplateRendererInterface $template) { @@ -191,22 +191,22 @@ class AlbumPage extends AbstractPage > ```php > namespace App\Action; -> +> > use Fig\Http\Message\StatusCodeInterface as StatusCode; > use Interop\Http\ServerMiddleware\DelegateInterface; > use Psr\Http\Message\ServerRequestInterface; > use Zend\Diactoros\Response\EmptyResponse; -> +> > trait ActionBasedInvocation > { > public function process(ServerRequestInterface $request, DelegateInterface $delegate) > { > $action = $request->getAttribute('action', 'index') . 'Action'; -> +> > if (! method_exists($this, $action)) { > return new EmptyResponse(StatusCode::STATUS_NOT_FOUND); > } -> +> > return $this->$action($request, $delegate); > } > } @@ -217,21 +217,21 @@ class AlbumPage extends AbstractPage > ```php > namespace Album\Action; -> +> > use App\Action\ActionBasedInvocation; > use Zend\Expressive\Template\TemplateRendererInterface; -> +> > class AlbumPage > { > use ActionBasedInvocation; -> -> private $template; -> +> +> private $template; +> > public function __construct(TemplateRendererInterface $template) > { > $this->template = $template; > } -> +> > public function indexAction( /* ... */ ) { /* ... */ } > public function addAction( /* ... */ ) { /* ... */ } > public function editAction( /* ... */ ) { /* ... */ } diff --git a/doc/book/cookbook/using-zend-form-view-helpers.md b/docs/book/cookbook/using-zend-form-view-helpers.md similarity index 100% rename from doc/book/cookbook/using-zend-form-view-helpers.md rename to docs/book/cookbook/using-zend-form-view-helpers.md diff --git a/doc/book/css/zend-expressive.css b/docs/book/css/zend-expressive.css similarity index 100% rename from doc/book/css/zend-expressive.css rename to docs/book/css/zend-expressive.css diff --git a/doc/book/features/application.md b/docs/book/features/application.md similarity index 100% rename from doc/book/features/application.md rename to docs/book/features/application.md diff --git a/doc/book/features/container/aura-di.md b/docs/book/features/container/aura-di.md similarity index 100% rename from doc/book/features/container/aura-di.md rename to docs/book/features/container/aura-di.md diff --git a/doc/book/features/container/delegator-factories.md b/docs/book/features/container/delegator-factories.md similarity index 100% rename from doc/book/features/container/delegator-factories.md rename to docs/book/features/container/delegator-factories.md diff --git a/doc/book/features/container/factories.md b/docs/book/features/container/factories.md similarity index 99% rename from doc/book/features/container/factories.md rename to docs/book/features/container/factories.md index 1d78a365..86cdd9d3 100644 --- a/doc/book/features/container/factories.md +++ b/docs/book/features/container/factories.md @@ -1,7 +1,7 @@ # Provided Factories Expressive provides several factories compatible with -[PSR-11 Container](https://github.com/php-fig/container) to facilitate +[PSR-11 Container](https://github.com/php-fig/container) to facilitate setting up common dependencies. The following is a list of provided containers, what they will create, the suggested service name, and any additional dependencies they may require. @@ -41,7 +41,7 @@ order to seed the `Application` instance: `middleware_pipeline` and `routes` configuration are ignored, and the factory will assume that these are injected programmatically elsewhere. -- `raise_throwables` (bool) (Since 1.1.0; obsolete as of 2.0.0): when enabled, +- `raise_throwables` (bool) (Since 1.1.0; obsolete as of 2.0.0): when enabled, this flag will prevent the Stratigility middleware dispatcher from catching exceptions, and instead allow them to bubble outwards. @@ -84,12 +84,12 @@ order to seed the `Application` instance: service name resolving to valid middleware, middleware instances (either http-interop middleware or callable double-pass middleware), or an array of these values. If an array is provided, the specified middleware will be - composed into a `Zend\Stratigility\MiddlewarePipe` instance. - + composed into a `Zend\Stratigility\MiddlewarePipe` instance. + If the `path` key is present, that key will be used to segregate the middleware to a specific matched path (in other words, it will not execute if the path is not matched). - + The `priority` defaults to 1, and follows the semantics of [SplPriorityQueue](http://php.net/SplPriorityQueue): higher integer values indicate higher priority (will execute earlier), while lower/negative integer @@ -100,7 +100,7 @@ order to seed the `Application` instance: You *can* specify keys for each middleware specification. These will be ignored by the factory, but can be useful when merging several configurations into one for the application. - + Under Expressive 1.X, if the `error` key is present and boolean `true`, then the middleware will be registered as error middleware. (This is necessary due to the fact that the factory defines a callable wrapper around middleware to @@ -130,7 +130,7 @@ order to seed the `Application` instance: - `path`: the path to match. Format will be based on the router you choose for your project. - + - `middleware`: a service name resolving to valid middleware, valid middleware (either http-interop middleware or callable double-pass middleware), or an array of such values (which will be composed into @@ -141,10 +141,10 @@ order to seed the `Application` instance: - `allowed_methods`: an array of allowed HTTP methods. If not provided, the application assumes any method is allowed. - + - `name`: if not provided, the path will be used as the route name (and, if specific HTTP methods are allowed, a list of those). - + - `options`: a key/value set of additional options to pass to the underlying router implementation for the given route. (Typical use cases include passing constraints or default values.) diff --git a/doc/book/features/container/intro.md b/docs/book/features/container/intro.md similarity index 100% rename from doc/book/features/container/intro.md rename to docs/book/features/container/intro.md diff --git a/doc/book/features/container/pimple.md b/docs/book/features/container/pimple.md similarity index 99% rename from doc/book/features/container/pimple.md rename to docs/book/features/container/pimple.md index b4552e5f..e07f09cb 100644 --- a/doc/book/features/container/pimple.md +++ b/docs/book/features/container/pimple.md @@ -107,7 +107,7 @@ $app->run(); ``` > ### Environments -> +> > In the example above, we provide two alternate definitions for > either the service `Zend\Expressive\FinalHandler` (Expressive 1.X) or the > service `Zend\Expressive\Middleware\ErrorResponseGenerator` (Expressive 2.X), diff --git a/doc/book/features/container/zend-servicemanager.md b/docs/book/features/container/zend-servicemanager.md similarity index 100% rename from doc/book/features/container/zend-servicemanager.md rename to docs/book/features/container/zend-servicemanager.md diff --git a/doc/book/features/emitters.md b/docs/book/features/emitters.md similarity index 100% rename from doc/book/features/emitters.md rename to docs/book/features/emitters.md diff --git a/doc/book/features/error-handling.md b/docs/book/features/error-handling.md similarity index 99% rename from doc/book/features/error-handling.md rename to docs/book/features/error-handling.md index e9aa1a4a..fcf5a96f 100644 --- a/doc/book/features/error-handling.md +++ b/docs/book/features/error-handling.md @@ -111,7 +111,7 @@ return [ > > You can specify the above in one of your `config/autoload/*.global.php` files, > to ensure you have a production-capable error response generator. -> +> > If you are using [zf-development-mode](https://github.com/zfcampus/zf-development-mode) > in your application (which is provided by default in the Expressive 2.0 > skeleton), you can toggle usage of whoops by adding configuration to the file @@ -120,7 +120,7 @@ return [ > ```php > use Zend\Expressive\Container; > use Zend\Expressive\Middleware; -> +> > return [ > 'dependencies' => [ > 'factories' => [ @@ -477,7 +477,7 @@ $finalHandler = new WhoopsErrorHandler( $app = new Application($router, $container, $finalHandler); // Register Whoops just before running the application, as otherwise it can -// swallow bootstrap errors. +// swallow bootstrap errors. $whoops->register(); $app->run(); ``` diff --git a/doc/book/features/helpers/body-parse.md b/docs/book/features/helpers/body-parse.md similarity index 100% rename from doc/book/features/helpers/body-parse.md rename to docs/book/features/helpers/body-parse.md diff --git a/doc/book/features/helpers/content-length.md b/docs/book/features/helpers/content-length.md similarity index 100% rename from doc/book/features/helpers/content-length.md rename to docs/book/features/helpers/content-length.md diff --git a/doc/book/features/helpers/intro.md b/docs/book/features/helpers/intro.md similarity index 100% rename from doc/book/features/helpers/intro.md rename to docs/book/features/helpers/intro.md diff --git a/doc/book/features/helpers/server-url-helper.md b/docs/book/features/helpers/server-url-helper.md similarity index 100% rename from doc/book/features/helpers/server-url-helper.md rename to docs/book/features/helpers/server-url-helper.md diff --git a/doc/book/features/helpers/url-helper.md b/docs/book/features/helpers/url-helper.md similarity index 99% rename from doc/book/features/helpers/url-helper.md rename to docs/book/features/helpers/url-helper.md index ab0caca0..9c377300 100644 --- a/doc/book/features/helpers/url-helper.md +++ b/docs/book/features/helpers/url-helper.md @@ -75,7 +75,7 @@ Each method will raise an exception if: In order to use the helper, you will need to instantiate it with the current `RouterInterface`. The factory `Zend\Expressive\Helper\UrlHelperFactory` has been provided for this purpose, and can be used trivially with most -dependency injection containers implementing +dependency injection containers implementing [PSR-11 Container](https://github.com/php-fig/container). Additionally, it is most useful when injected with the current results of routing, which requires registering middleware with the application that can inject the route diff --git a/doc/book/features/middleware-types.md b/docs/book/features/middleware-types.md similarity index 99% rename from doc/book/features/middleware-types.md rename to docs/book/features/middleware-types.md index b4afbf97..f6528bc3 100644 --- a/doc/book/features/middleware-types.md +++ b/docs/book/features/middleware-types.md @@ -32,7 +32,7 @@ Expressive allows you to define middleware using any of the following: The http-interop/http-middleware project is the basis for the proposed PSR-15 specification, which covers HTTP Server Middleware that consumes [PSR-7](http://www.php-fig.org/psr/psr-7/) HTTP messages. The project defines two -interfaces, `Interop\Http\ServerMiddleware\MiddlewareInterface` and +interfaces, `Interop\Http\ServerMiddleware\MiddlewareInterface` and `Interop\Http\ServerMiddleware\DelegateInterface`. Expressive accepts middleware that implements the `MiddlewareInterface`. As an example: diff --git a/doc/book/features/middleware/implicit-methods-middleware.md b/docs/book/features/middleware/implicit-methods-middleware.md similarity index 99% rename from doc/book/features/middleware/implicit-methods-middleware.md rename to docs/book/features/middleware/implicit-methods-middleware.md index 8afc5f90..7d7ecc8e 100644 --- a/doc/book/features/middleware/implicit-methods-middleware.md +++ b/docs/book/features/middleware/implicit-methods-middleware.md @@ -130,4 +130,4 @@ One thing to note: the allowed methods reported by the route and/or route result, and returned via the `Allow` header, may vary based on router implementation. In most cases, it should be an aggregate of all routes using the same path specification; however, it *could* be only the methods supported -explicitly by the matched route. +explicitly by the matched route. diff --git a/doc/book/features/modular-applications.md b/docs/book/features/modular-applications.md similarity index 100% rename from doc/book/features/modular-applications.md rename to docs/book/features/modular-applications.md diff --git a/doc/book/features/router/aura.md b/docs/book/features/router/aura.md similarity index 99% rename from doc/book/features/router/aura.md rename to docs/book/features/router/aura.md index 47434cd9..685a4eea 100644 --- a/doc/book/features/router/aura.md +++ b/docs/book/features/router/aura.md @@ -92,7 +92,7 @@ $app = AppFactory::create(null, $router); ## Factory-Driven Creation [We recommend using an Inversion of Control container](../container/intro.md) -for your applications; as such, in this section we will demonstrate +for your applications; as such, in this section we will demonstrate two strategies for creating your Aura.Router implementation. ### Basic Router diff --git a/doc/book/features/router/fast-route.md b/docs/book/features/router/fast-route.md similarity index 98% rename from doc/book/features/router/fast-route.md rename to docs/book/features/router/fast-route.md index 8b3813bf..c748a859 100644 --- a/doc/book/features/router/fast-route.md +++ b/docs/book/features/router/fast-route.md @@ -88,7 +88,7 @@ $app = AppFactory::create(null, $router); ## Factory-Driven Creation [We recommend using an Inversion of Control container](../container/intro.md) -for your applications; as such, in this section we will demonstrate +for your applications; as such, in this section we will demonstrate two strategies for creating your FastRoute implementation. ### Basic Router @@ -275,7 +275,7 @@ $container[Zend\Expressive\Router\RouterInterface::class] = new RouterFactory(); - Since zend-expressive-fastroute 1.3.0. -Starting from version 1.3.0, zend-expressive-fastroute comes with support +Starting from version 1.3.0, zend-expressive-fastroute comes with support for FastRoute native dispatch data caching. Enabling this feature requires changes to your configuration. Typically, router @@ -286,7 +286,7 @@ The changes required are: - You will need to delegate creation of the router instance to a new factory. -- You will need to add a new configuration entry, `$config['router']['fastroute']`. +- You will need to add a new configuration entry, `$config['router']['fastroute']`. The options in this entry will be used by the factory to build the router instance in order to toggle caching support and to specify a custom cache file. @@ -312,7 +312,7 @@ return [ /* ... */ ], ], - + // Add the following to enable caching support: 'router' => [ 'fastroute' => [ @@ -329,16 +329,16 @@ return [ The FastRoute-specific caching options are as follows: -- `cache_enabled` (bool) is used to toggle caching support. It's advisable to enable +- `cache_enabled` (bool) is used to toggle caching support. It's advisable to enable caching in a production environment and leave it disabled for the development environment. Commenting or omitting this option is equivalent to having it set to `false`. We recommend enabling it in `config/autoload/routes.global.php`, and, in development, disabling it within `config/autoload/routes.local.php` or `config/autoload/local.php`. -- `cache_file` (string) is an optional parameter that represents the path of +- `cache_file` (string) is an optional parameter that represents the path of the dispatch data cache file. It can be provided as an absolute file path or - as a path relative to the zend-expressive working directory. + as a path relative to the zend-expressive working directory. It defaults to `data/cache/fastroute.php.cache`, where `data/cache/` is the cache directory defined within the zend-expressive skeleton application. An diff --git a/doc/book/features/router/interface.md b/docs/book/features/router/interface.md similarity index 99% rename from doc/book/features/router/interface.md rename to docs/book/features/router/interface.md index 7fb50748..27267d6a 100644 --- a/doc/book/features/router/interface.md +++ b/docs/book/features/router/interface.md @@ -87,7 +87,7 @@ correctly. > array $substitutions = [] > ) : string > ``` -> +> > If you are targeting that version, you may still provide the `$options` > argument, but it will not be invoked. diff --git a/doc/book/features/router/intro.md b/docs/book/features/router/intro.md similarity index 100% rename from doc/book/features/router/intro.md rename to docs/book/features/router/intro.md diff --git a/doc/book/features/router/piping.md b/docs/book/features/router/piping.md similarity index 99% rename from doc/book/features/router/piping.md rename to docs/book/features/router/piping.md index b7ed08dc..7af9790d 100644 --- a/doc/book/features/router/piping.md +++ b/docs/book/features/router/piping.md @@ -41,24 +41,24 @@ fetch and dispatch the middleware inside a no overhead to utilizing service-based middleware _until it is dispatched_. > ### Service-based middleware in version 1 -> +> > In Expressive 1.X versions, lazy-loading middleware was handled by wrapping > the middleware inside a closure which composed the container. -> +> > This posed a problem for Stratigility 1.X-style error handling middleware, as > zend-stratigility identified error handling middleware by its arity (number of > function arguments); as such, zend-expressive defined an additional method for > piping service-driven error handling middleware, `pipeErrorHandler()`. That > method had the same signature as `pipe()`: -> +> > ```php > // Without a path: > $app->pipeErrorHandler('error handler service name'); -> +> > // Specific to a path: > $app->pipeErrorHandler('/api', 'error handler service name'); > ``` -> +> > That method returned a closure using the error middleware signature. > > As noted in the [error handling chapter](../error-handling.md), you should diff --git a/doc/book/features/router/uri-generation.md b/docs/book/features/router/uri-generation.md similarity index 100% rename from doc/book/features/router/uri-generation.md rename to docs/book/features/router/uri-generation.md diff --git a/doc/book/features/router/zf2.md b/docs/book/features/router/zf2.md similarity index 99% rename from doc/book/features/router/zf2.md rename to docs/book/features/router/zf2.md index 82acdedb..d2066417 100644 --- a/doc/book/features/router/zf2.md +++ b/docs/book/features/router/zf2.md @@ -91,7 +91,7 @@ $app = AppFactory::create(null, $router); ## Factory-Driven Creation [We recommend using an Inversion of Control container](../container/intro.md) -for your applications; as such, in this section we will demonstrate +for your applications; as such, in this section we will demonstrate two strategies for creating your zend-mvc router implementation. ### Basic Router diff --git a/doc/book/features/template/interface.md b/docs/book/features/template/interface.md similarity index 100% rename from doc/book/features/template/interface.md rename to docs/book/features/template/interface.md diff --git a/doc/book/features/template/intro.md b/docs/book/features/template/intro.md similarity index 100% rename from doc/book/features/template/intro.md rename to docs/book/features/template/intro.md diff --git a/doc/book/features/template/middleware.md b/docs/book/features/template/middleware.md similarity index 100% rename from doc/book/features/template/middleware.md rename to docs/book/features/template/middleware.md diff --git a/doc/book/features/template/plates.md b/docs/book/features/template/plates.md similarity index 100% rename from doc/book/features/template/plates.md rename to docs/book/features/template/plates.md diff --git a/doc/book/features/template/twig.md b/docs/book/features/template/twig.md similarity index 100% rename from doc/book/features/template/twig.md rename to docs/book/features/template/twig.md diff --git a/doc/book/features/template/zend-view.md b/docs/book/features/template/zend-view.md similarity index 99% rename from doc/book/features/template/zend-view.md rename to docs/book/features/template/zend-view.md index 7923e408..52ee68d7 100644 --- a/doc/book/features/template/zend-view.md +++ b/docs/book/features/template/zend-view.md @@ -71,7 +71,7 @@ $renderer = new ZendViewRenderer($renderer); > resolver to it. > - A `NamespacedPathStackResolver` is registered with the `AggregateResolver`, at > a low priority (0), ensuring attempts to resolve hit it later. -> +> > With resolvers such as the `TemplateMapResolver`, you can also resolve > namespaced templates, mapping them directly to the template on the filesystem > that matches; adding such a resolver can be a nice performance boost! diff --git a/doc/book/getting-started/features.md b/docs/book/getting-started/features.md similarity index 99% rename from doc/book/getting-started/features.md rename to docs/book/getting-started/features.md index 11a5e912..a1e0e617 100644 --- a/doc/book/getting-started/features.md +++ b/docs/book/getting-started/features.md @@ -31,7 +31,7 @@ to provide a robust convenience layer on which to build applications. The features it provides include: - **Routing** - + Stratigility provides limited, literal matching only. Expressive allows you to utilize dynamic routing capabilities from a variety of routers, providing much more fine-grained matching capabilities. The routing layer also allows @@ -83,13 +83,13 @@ Any given middleware can return a *response*, at which point execution winds its way back out the onion. > ### Pipelines -> +> > The terminology "pipeline" is often used to describe the onion. One way of > looking at the "onion" is as a *queue*, which is first-in-first-out (FIFO) in > operation. This means that the first middleware on the queue is executed first, > and this invokes the next, and so on (and hence the "next" terminology). When > looked at from this perspective: -> +> > - In most cases, the entire queue *will not* be traversed. > - The inner-most layer of the onion represents the last item in the queue, and > should be guaranteed to return a response; usually this is indicative of @@ -127,7 +127,7 @@ its way back out the onion. > > It is termed "double pass" because you pass both the request and response when > delegating to the next layer. -> +> > Expressive 2.X still supports double-pass middleware, though we recommend the > lambda style. diff --git a/doc/book/getting-started/skeleton.md b/docs/book/getting-started/skeleton.md similarity index 97% rename from doc/book/getting-started/skeleton.md rename to docs/book/getting-started/skeleton.md index 7669fd79..a47a447c 100644 --- a/doc/book/getting-started/skeleton.md +++ b/docs/book/getting-started/skeleton.md @@ -71,7 +71,7 @@ Starting in version 2 of the skeleton, we ship tools to make development easier. ### Development Mode -[zf-development-mode](https://github.com/zfcampus/zf-development-mode) allows +[zf-development-mode](https://github.com/zfcampus/zf-development-mode) allows you to enable and disable development mode from your cli. ```bash @@ -81,12 +81,12 @@ $ composer development-status # show development status ``` The development configuration is set in `config/autoload/development.local.php.dist`. -It also allows you to specify configuration and modules that should only be enabled +It also allows you to specify configuration and modules that should only be enabled when in development, and not when in production. ### Clear config cache -Production settings are the default, which means enabling the configuration cache. +Production settings are the default, which means enabling the configuration cache. However, it must be easy for developers to clear the configuration cache. That's what this command does. @@ -96,10 +96,10 @@ $ composer clear-config-cache ### Testing Your Code -[PHPUnit](https://github.com/sebastianbergmann/phpunit) and +[PHPUnit](https://github.com/sebastianbergmann/phpunit) and [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) are now installed by default. To execute tests and detect coding standards violations, -run the following command: +run the following command: ```bash $ composer check @@ -132,8 +132,8 @@ application. ### Component Installer -Whenever you add a component or module that exposes itself as such, the -[zend-component-installer](https://zendframework.github.io/zend-component-installer/) +Whenever you add a component or module that exposes itself as such, the +[zend-component-installer](https://docs.zendframework.com/zend-component-installer/) composer plugin will prompt you, asking if and where you want to inject its configuration. This ensures that components are wired automatically for you. @@ -144,7 +144,7 @@ tools intended only for usage during development, choose ### Config Aggregator The [zend-config-aggregator](https://github.com/zendframework/zend-config-aggregator) -library collects and merges configuration from different sources. It also supports +library collects and merges configuration from different sources. It also supports configuration caching. As an example, your `config/config.php` file might read as follows in order to @@ -175,7 +175,7 @@ $aggregator = new ConfigAggregator([ return $aggregator->getMergedConfig(); ``` -The configuration is merged in the same order as it is passed, with later entries +The configuration is merged in the same order as it is passed, with later entries having precedence. ### Config Providers @@ -185,7 +185,7 @@ constructor. Each provider should be a callable class that requires no constructor parameters, where invocation returns a configuration array (or a PHP generator) to be merged. -Libraries or modules can have configuration providers that provide default values +Libraries or modules can have configuration providers that provide default values for a library or module. For the `UserModule\ConfigProvider` class loaded in the `ConfigAggregator` above, the `ConfigProvider` might look like this: @@ -277,47 +277,47 @@ documentation](../reference/cli-tooling.md#modules). ## Adding Middleware The skeleton makes the assumption that you will be writing your middleware as -classes, and uses [piping and routing](../features/router/piping.md) to add +classes, and uses [piping and routing](../features/router/piping.md) to add your middleware. ### Piping -[Piping](../features/router/piping.md#piping) is a foundation feature of the +[Piping](../features/router/piping.md#piping) is a foundation feature of the underlying [zend-stratigility](https://docs.zendframework.com/zend-stratigility/) implementation. You can setup the middleware pipeline in `config/pipeline.php`. In this section, we'll demonstrate setting up a basic pipeline that includes error handling, segregated applications, routing, middleware dispatch, and more. -The error handler should be the first (most outer) middleware to catch all +The error handler should be the first (most outer) middleware to catch all exceptions. ```php $app->pipe(ErrorHandler::class); -$app->pipe(ServerUrlMiddleware::class); +$app->pipe(ServerUrlMiddleware::class); ``` -After the `ErrorHandler` you can pipe more middleware that you want to execute -on every request, such as bootstrapping, pre-conditions, and modifications to +After the `ErrorHandler` you can pipe more middleware that you want to execute +on every request, such as bootstrapping, pre-conditions, and modifications to outgoing responses: ```php -$app->pipe(ServerUrlMiddleware::class); +$app->pipe(ServerUrlMiddleware::class); ``` -Piped middleware may be either callables or service names. Middleware may also -be passed as an array; each item in the array must resolve to middleware +Piped middleware may be either callables or service names. Middleware may also +be passed as an array; each item in the array must resolve to middleware eventually (i.e., callable or service name); underneath, Expressive creates `Zend\Stratigility\MiddlewarePipe` instances with each of the middleware listed piped to it. Middleware can be attached to specific paths, allowing you to mix and match -applications under a common domain. The handlers in each middleware attached +applications under a common domain. The handlers in each middleware attached this way will see a URI with the **MATCHED PATH SEGMENT REMOVED!!!** ```php $app->pipe('/api', $apiMiddleware); $app->pipe('/docs', $apiDocMiddleware); -$app->pipe('/files', $filesMiddleware); +$app->pipe('/files', $filesMiddleware); ``` Next, you should register the routing middleware in the middleware pipeline: @@ -326,7 +326,7 @@ Next, you should register the routing middleware in the middleware pipeline: $app->pipeRoutingMiddleware(); ``` -Add more middleware that needs to introspect the routing results; this might +Add more middleware that needs to introspect the routing results; this might include: - handling for HTTP `HEAD` requests @@ -386,7 +386,7 @@ $app->pipe(NotFoundHandler::class); ``` ### Routing - + [Routing](../features/router/piping.md#routing) is an additional feature provided by Expressive. Routing is setup in `config/routes.php`. @@ -420,7 +420,7 @@ $app->route( App\Action\ContactAction::class, Zend\Expressive\Router\Route::HTTP_METHOD_ANY, 'contact' -); +); ``` We recommend a single middleware class per combination of route and request @@ -428,7 +428,7 @@ method. ## Next Steps -The skeleton provides a default structure for templates, if you choose to use them. +The skeleton provides a default structure for templates, if you choose to use them. Let's see how you can create your first vanilla middleware, and templated middleware. ### Creating middleware @@ -445,24 +445,24 @@ single method, `process()`, which accepts a > "double-pass", for the fact that it passes both the request and response between > layers. This middleware did not require an interface, and relied on a > conventional definition of: -> +> > ```php > use Psr\Http\Message; -> +> > function ( > Message\ServerRequestInterface $request, > Message\ResponseInterface $response, > callable $next > ) : Message\ResponseInterface > ``` -> +> > While this style of middleware is still quite wide-spread and used in a number > of projects, it has some flaws. Chief among them is the fact that middleware > should not rely on the `$response` instance provided to them (as it may have > modifications unacceptable for the current context), and that a response > returned from inner layers may not be based off the `$response` provided to them > (as inner layers may create and return a completely different response). -> +> > Starting in Expressive 2.0, we add support for > [http-interop/http-middleware](https://github.com/http-interop/http-middleware), > which is a working group of [PHP-FIG](http://www.php-fig.org/) dedicated to @@ -470,7 +470,7 @@ single method, `process()`, which accepts a > a "single-pass" or "lambda" architecture, whereby only the request instance is > passed between layers. We now recommend writing middleware using the > http-middleware interfaces for all new middleware. -> +> > Middleware using the double-pass style is still accepted by Expressive, but > support for it will be discontinued once http-middleware is formally approved > by PHP-FIG. @@ -609,7 +609,7 @@ The above modifies the class to accept a renderer to the constructor, and then calls on it to render a template. Note that we no longer need to escape our target; the template takes care of that for us. -How does the template renderer get into the action? The answer is dependency +How does the template renderer get into the action? The answer is dependency injection. For the next part of the example, we'll be creating and wiring a factory for diff --git a/doc/book/getting-started/standalone.md b/docs/book/getting-started/standalone.md similarity index 100% rename from doc/book/getting-started/standalone.md rename to docs/book/getting-started/standalone.md diff --git a/doc/book/images/architecture.dia b/docs/book/images/architecture.dia similarity index 100% rename from doc/book/images/architecture.dia rename to docs/book/images/architecture.dia diff --git a/doc/book/images/architecture.png b/docs/book/images/architecture.png similarity index 100% rename from doc/book/images/architecture.png rename to docs/book/images/architecture.png diff --git a/doc/book/images/architecture.svg b/docs/book/images/architecture.svg similarity index 100% rename from doc/book/images/architecture.svg rename to docs/book/images/architecture.svg diff --git a/doc/book/images/architecture.xcf b/docs/book/images/architecture.xcf similarity index 100% rename from doc/book/images/architecture.xcf rename to docs/book/images/architecture.xcf diff --git a/doc/book/images/check.png b/docs/book/images/check.png similarity index 100% rename from doc/book/images/check.png rename to docs/book/images/check.png diff --git a/doc/book/images/check.svg b/docs/book/images/check.svg similarity index 100% rename from doc/book/images/check.svg rename to docs/book/images/check.svg diff --git a/doc/book/images/error.png b/docs/book/images/error.png similarity index 100% rename from doc/book/images/error.png rename to docs/book/images/error.png diff --git a/doc/book/images/error.svg b/docs/book/images/error.svg similarity index 100% rename from doc/book/images/error.svg rename to docs/book/images/error.svg diff --git a/doc/book/images/installer.png b/docs/book/images/installer.png similarity index 100% rename from doc/book/images/installer.png rename to docs/book/images/installer.png diff --git a/doc/book/images/lambda.png b/docs/book/images/lambda.png similarity index 100% rename from doc/book/images/lambda.png rename to docs/book/images/lambda.png diff --git a/doc/book/images/lambda.svg b/docs/book/images/lambda.svg similarity index 100% rename from doc/book/images/lambda.svg rename to docs/book/images/lambda.svg diff --git a/doc/book/images/network.png b/docs/book/images/network.png similarity index 100% rename from doc/book/images/network.png rename to docs/book/images/network.png diff --git a/doc/book/images/network.svg b/docs/book/images/network.svg similarity index 100% rename from doc/book/images/network.svg rename to docs/book/images/network.svg diff --git a/doc/book/images/pencil.png b/docs/book/images/pencil.png similarity index 100% rename from doc/book/images/pencil.png rename to docs/book/images/pencil.png diff --git a/doc/book/images/pencil.svg b/docs/book/images/pencil.svg similarity index 100% rename from doc/book/images/pencil.svg rename to docs/book/images/pencil.svg diff --git a/doc/book/images/syringe.png b/docs/book/images/syringe.png similarity index 100% rename from doc/book/images/syringe.png rename to docs/book/images/syringe.png diff --git a/doc/book/images/syringe.svg b/docs/book/images/syringe.svg similarity index 100% rename from doc/book/images/syringe.svg rename to docs/book/images/syringe.svg diff --git a/doc/book/index.html b/docs/book/index.html similarity index 100% rename from doc/book/index.html rename to docs/book/index.html diff --git a/doc/book/index.md b/docs/book/index.md similarity index 100% rename from doc/book/index.md rename to docs/book/index.md diff --git a/doc/book/reference/cli-tooling.md b/docs/book/reference/cli-tooling.md similarity index 100% rename from doc/book/reference/cli-tooling.md rename to docs/book/reference/cli-tooling.md diff --git a/doc/book/reference/expressive-projects.md b/docs/book/reference/expressive-projects.md similarity index 98% rename from doc/book/reference/expressive-projects.md rename to docs/book/reference/expressive-projects.md index 58aa79df..bc13ebaf 100644 --- a/doc/book/reference/expressive-projects.md +++ b/docs/book/reference/expressive-projects.md @@ -1,17 +1,17 @@ -# Projects powered by zend-expressive - -zend-expressive can be used for anything. Here are some projects, tutorials and -the related source code. Have a look around and see how others have used -zend-expressive. - -## Sample Code & Tutorials -- Expressive Tutorial (WIP) - [*source*](https://github.com/RalfEggert/zend-expressive-tutorial) -- [AstroSplash](http://astrosplash.com/) - [*source*](https://github.com/AndrewCarterUK/AstroSplash) - (Also, read the [related article on sitepoint](http://www.sitepoint.com/build-nasa-photo-gallery-zend-expressive/)) -- [php-ddd-cargo-sample](https://codeliner.github.io/php-ddd-cargo-sample/) - [*source*](https://github.com/codeliner/php-ddd-cargo-sample) - -## Personal Sites -- [mwop.net](https://mwop.net/) - [*source*](https://github.com/weierophinney/mwop.net) -- [xtreamwayz.com](https://xtreamwayz.com/) - [*source*](https://github.com/xtreamwayz/xtreamwayz.com) -- [alejandrocelaya.com](http://www.alejandrocelaya.com/) - [*source*](https://github.com/acelaya/website-expressive) -- [zimuel.it](http://www.zimuel.it) - [*source*](https://github.com/ezimuel/zimuel.it) +# Projects powered by zend-expressive + +zend-expressive can be used for anything. Here are some projects, tutorials and +the related source code. Have a look around and see how others have used +zend-expressive. + +## Sample Code & Tutorials +- Expressive Tutorial (WIP) - [*source*](https://github.com/RalfEggert/zend-expressive-tutorial) +- [AstroSplash](http://astrosplash.com/) - [*source*](https://github.com/AndrewCarterUK/AstroSplash) + (Also, read the [related article on sitepoint](http://www.sitepoint.com/build-nasa-photo-gallery-zend-expressive/)) +- [php-ddd-cargo-sample](https://codeliner.github.io/php-ddd-cargo-sample/) - [*source*](https://github.com/codeliner/php-ddd-cargo-sample) + +## Personal Sites +- [mwop.net](https://mwop.net/) - [*source*](https://github.com/weierophinney/mwop.net) +- [xtreamwayz.com](https://xtreamwayz.com/) - [*source*](https://github.com/xtreamwayz/xtreamwayz.com) +- [alejandrocelaya.com](http://www.alejandrocelaya.com/) - [*source*](https://github.com/acelaya/website-expressive) +- [zimuel.it](http://www.zimuel.it) - [*source*](https://github.com/ezimuel/zimuel.it) diff --git a/doc/book/reference/migration/rc-to-v1.md b/docs/book/reference/migration/rc-to-v1.md similarity index 100% rename from doc/book/reference/migration/rc-to-v1.md rename to docs/book/reference/migration/rc-to-v1.md diff --git a/doc/book/reference/migration/to-v1-1.md b/docs/book/reference/migration/to-v1-1.md similarity index 100% rename from doc/book/reference/migration/to-v1-1.md rename to docs/book/reference/migration/to-v1-1.md diff --git a/doc/book/reference/migration/to-v2.md b/docs/book/reference/migration/to-v2.md similarity index 99% rename from doc/book/reference/migration/to-v2.md rename to docs/book/reference/migration/to-v2.md index 8ee7c556..fc5a1e6f 100644 --- a/doc/book/reference/migration/to-v2.md +++ b/docs/book/reference/migration/to-v2.md @@ -118,7 +118,7 @@ release: In previous versions of Expressive, we consumed [container-interop](https://github.com/container-interop/container-interop), which provides `Interop\Container\ContainerInterface`, a shared interface for -dependency injection containers. container-interop served as a working group for the +dependency injection containers. container-interop served as a working group for the [PSR-11](http://www.php-fig.org/psr/psr-11/) specification. In the weeks prior to the Expressive 2.0 release, PSR-11 was formally accepted, @@ -177,7 +177,7 @@ Specifically, your middleware can now implement: Interop\Http\ServerMiddleware\DelegateInterface $delegate)`. - Callable middleware that follows the above signature (the typehint for the request argument is optional). - + Both styles of middleware may be piped directly to the middleware pipeline or as routed middleware within Expressive. In each case, you can invoke the next middleware layer using `$delegate->process($request)`. @@ -323,7 +323,7 @@ function ( // caught PHP 5 exception } - // ... + // ... // do something with $exception and generate a response // ... @@ -394,7 +394,7 @@ handling needs: - The value of `zend-expressive.error_handler.template_error`, if present, will be used to seed the `$template` argument. -- `Zend\Expressive\Middleware\WhoopsErrorResponseGenerator` uses Whoops to +- `Zend\Expressive\Middleware\WhoopsErrorResponseGenerator` uses Whoops to generate the error response. Its constructor takes a single argument, a `Whoops\Run` instance. If a `Whoops\Handler\PrettyPageHandler` is registered with the instance, it will add a data table with request details derived from @@ -549,7 +549,7 @@ no longer supported with Stratigility version 2 and Expressive 2.0. You will need to find any instances of them in your application, or cases where your middleware invokes error middleware via the third argument to `$next()`. -We provide a tool to assist you with that via the package +We provide a tool to assist you with that via the package [zendframework/zend-expressive-tooling](https://github.com/zendframework/zend-expressive-tooling): `vendor/bin/expressive-scan-for-error-middleware`. Run the command from your project root, optionally passing the `help`, `--help`, or `-h` commands for @@ -666,7 +666,7 @@ This command does the following: - Reads your `routes` configuration, and generates a programmatic routing table for you, which is then stored in `config/routes.php`. -- Adds a new configuration file, `config/autoload/programmatic-pipeline.global.php`, +- Adds a new configuration file, `config/autoload/programmatic-pipeline.global.php`, which enables the `programmatic_pipelines` configuration flag. Additionally, it adds dependency configuration for the new error handlers. diff --git a/doc/book/reference/usage-examples.md b/docs/book/reference/usage-examples.md similarity index 100% rename from doc/book/reference/usage-examples.md rename to docs/book/reference/usage-examples.md diff --git a/doc/book/why-expressive.md b/docs/book/why-expressive.md similarity index 100% rename from doc/book/why-expressive.md rename to docs/book/why-expressive.md diff --git a/mkdocs.yml b/mkdocs.yml index 2cb97a3f..005b8b2f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ -docs_dir: doc/book -site_dir: doc/html +docs_dir: docs/book +site_dir: docs/html pages: - index.md - 'Getting Started': @@ -69,6 +69,6 @@ pages: site_name: Expressive site_description: 'zend-expressive: PSR-7 Middleware Microframework' repo_url: 'https://github.com/zendframework/zend-expressive' -copyright: 'Copyright (c) 2016 Zend Technologies USA Inc.' +copyright: 'Copyright (c) 2015-2017 Zend Technologies USA Inc.' extra_css: - css/zend-expressive.css