Merge pull request #691 from settermjd/update-the-docs

Clean up the docs

README.md

@@ -1,32 +1,37 @@
-# Slim-Website
+# The Slim Framework Website
 
-This is the repository for the Slim website at www.slimframework.com.
+This is the repository for the Slim website ([slimframework.com][slimframework-url]).
 
+## Want to contribute?
 
-## Contributing
+If you spot any errors, typos, or missing information, please submit [a pull request][pr-url].
 
-If you spot any errors, typos or missing information, please submit a pull
-request.
+### The documentation style guide
+
+Unless otherwise stated, the documentation follows [the AP Stylebook][ap-stylebook-url].
+
+### Are you a Microsoft Windows user
 
-### Windows User
 You need to make sure you have [Ruby Devkit Installed (MSYS2)](https://rubyinstaller.org/add-ons/devkit.html).
 
-### Running Locally
+### Building and running the documentation locally
 
 To run this site locally so that you can test your changes:
+
 ```bash
 $ sudo gem install bundler
 $ bundle install
 ```
 
-Now, run the local jekyll:
+Now, run the local [Jekyll][jekyll-url] installation:
+
 ```bash
 $ bundle exec jekyll serve
 ```
 
-and browse to http://localhost:4000
+Then, browse to http://localhost:4000 in your browser of choice.
 
-#### CSS
+#### Editing the site's CSS
 
 The CSS uses Less and is managed by `grunt`.
 
@@ -40,22 +45,28 @@ $ npm install
 To change any CSS, edit the appropriate files in `assets\less` and then run:
 
 ```bash
-$ grunt
+grunt
 ```
 
-You can also run `grunt watch` to automatically rebuild when you make CSS
-changes.
+You can also run `grunt watch` to automatically rebuild when you make CSS changes.
 
-### Build Instructions For Deployment
+### Build instructions for deployment
 
 ```bash
-$ bundle exec jekyll build
+bundle exec jekyll build
 ```
 
-### Update Algolia Search
-Ensure you set the environment variable `ALGOLIA_API_KEY` before running these commands. See [algolia docs](https://community.algolia.com/jekyll-algolia/getting-started.html) for more information
+### Update the Algolia search database
+
+Ensure you set the environment variable `ALGOLIA_API_KEY` before running these commands. 
+See [algolia docs](https://community.algolia.com/jekyll-algolia/getting-started.html) for more information.
 
 ```bash
-$ bundle install
-$ bundle exec jekyll algolia
+bundle install
+bundle exec jekyll algolia
 ```
+
+[ap-stylebook-url]: https://www.apstylebook.com
+[jekyll-url]: https://jekyllrb.com
+[pr-url]: https://github.com/slimphp/Slim-Website/compare
+[slimframework-url]: https://slimframework.com

docs/v4/concepts/di.md

@@ -2,15 +2,17 @@
 title: Dependency Container
 ---
 
-Slim uses an optional dependency container to prepare, manage, and inject application
-dependencies. Slim supports containers that implement [PSR-11](http://www.php-fig.org/psr/psr-11/) like [PHP-DI](http://php-di.org/doc/frameworks/slim.html).
+Slim uses an optional dependency container to prepare, manage, and inject application dependencies. 
+Slim supports containers that implement [PSR-11](http://www.php-fig.org/psr/psr-11/) like [PHP-DI](http://php-di.org/doc/frameworks/slim.html).
 
 ## Example usage with PHP-DI
 
-You don't _have_ to provide a dependency container. If you do, however, you must provide an instance of the container to `AppFactory` before creating an `App`.
+You don't _have_ to provide a dependency container. 
+If you do, however, you must provide an instance of the container to `AppFactory` before creating an `App`.
 
 ```php
 <?php
+
 use DI\Container;
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Message\ServerRequestInterface as Request;
@@ -35,8 +37,7 @@ $container->set('myService', function () {
 });
 ```
 
-You can fetch services from your container explicitly as well as from inside a Slim
-application route like this:
+You can fetch services from your container explicitly as well as from inside a Slim application route like this:
 
 ```php
 /**
@@ -79,8 +80,7 @@ $app->get('/foo', function (Request $request, Response $response, $args) {
 
 ## Configuring the application via a container
 
-In case you want to create the `App` with dependencies already defined in your container, 
-you can use the `AppFactory::createFromContainer()` method.
+In case you want to create the `App` with dependencies already defined in your container, you can use the `AppFactory::createFromContainer()` method.
 
 **Example**
 

docs/v4/concepts/life-cycle.md

@@ -6,28 +6,39 @@ title: Lifecycle
 
 ### 1. Instantiation
 
-First, you instantiate the `Slim\App` class. This is the Slim application object. During instantiation, Slim registers default services for each application dependency.
+First, you instantiate the `Slim\App` class. 
+This is the Slim application object. 
+During instantiation, Slim registers default services for each application dependency.
 
 ### 2. Route Definitions
 
-Second, you define routes using the application instance's `get()`, `post()`, `put()`, `delete()`, `patch()`, `head()`, and `options()` routing methods. These instance methods register a route with the application's Router object. Each routing method returns the Route instance so you can immediately invoke the Route instance's methods to add middleware or assign a name.
+Second, you define routes using the application instance's `get()`, `post()`, `put()`, `delete()`, `patch()`, `head()`, and `options()` routing methods. 
+These instance methods register a route with the application's Router object. 
+Each routing method returns the Route instance so you can immediately invoke the Route instance's methods to add middleware or assign a name.
 
 ### 3. Application Runner
 
-Third, you invoke the application instance's `run()` method. This method starts the following process:
+Third, you invoke the application instance's `run()` method. 
+This method starts the following process:
 
 #### A. Enter Middleware Stack
 
-The `run()` method begins to inwardly traverse the application's middleware stack. This is a concentric structure of middleware layers that receive (and optionally manipulate) the Environment, Request, and Response objects before (and after) the Slim application runs. The Slim application is the innermost layer of the concentric middleware structure. Each middleware layer is invoked inwardly beginning from the outermost layer.
+The `run()` method begins to inwardly traverse the application's middleware stack. 
+This is a concentric structure of middleware layers that receive (and optionally manipulate) the Environment, Request, and Response objects before (and after) the Slim application runs. 
+The Slim application is the innermost layer of the concentric middleware structure. 
+Each middleware layer is invoked inwardly beginning from the outermost layer.
 
 #### B. Run Application
 
-After the `run()` method reaches the innermost middleware layer, it invokes the application instance and dispatches the current HTTP request to the appropriate application route object. If a route matches the HTTP method and URI, the route's middleware and callable are invoked. If a matching route is not found, the Not Found or Not Allowed handler is invoked.
+After the `run()` method reaches the innermost middleware layer, it invokes the application instance and dispatches the current HTTP request to the appropriate application route object. 
+If a route matches the HTTP method and URI, the route's middleware and callable are invoked. 
+If a matching route is not found, the Not Found or Not Allowed handler is invoked.
 
 #### C. Exit Middleware Stack
 
 After the application dispatch process completes, each middleware layer reclaims control outwardly, beginning from the innermost layer.
 
 #### D. Send HTTP Response
 
-After the outermost middleware layer cedes control, the application instance prepares, serializes, and returns the HTTP response. The HTTP response headers are set with PHP's native `header()` method, and the HTTP response body is output to the current output buffer.
+After the outermost middleware layer cedes control, the application instance prepares, serializes, and returns the HTTP response. 
+The HTTP response headers are set with PHP's native `header()` method, and the HTTP response body is output to the current output buffer.

docs/v4/concepts/middleware.md

@@ -2,11 +2,12 @@
 title: Middleware
 ---
 
-You can run code _before_ and _after_ your Slim application to manipulate the
-Request and Response objects as you see fit. This is called _middleware_.
-Why would you want to do this? Perhaps you want to protect your app
-from cross-site request forgery. Maybe you want to authenticate requests
-before your app runs. Middleware is perfect for these scenarios.
+You can run code _before_ and _after_ your Slim application to manipulate the Request and Response objects as you see fit. 
+This is called _middleware_.
+Why would you want to do this? 
+Perhaps you want to protect your app from cross-site request forgery. 
+Maybe you want to authenticate requests before your app runs. 
+Middleware is perfect for these scenarios.
 
 ## What is middleware?
 
@@ -15,37 +16,33 @@ A middleware implements the [PSR-15 Middleware Interface](https://www.php-fig.or
 1. `Psr\Http\Message\ServerRequestInterface` - The PSR-7 request object
 2. `Psr\Http\Server\RequestHandlerInterface` - The PSR-15 request handler object
 
-It can do whatever is appropriate with these objects. The only hard requirement
-is that a middleware **MUST** return an instance of  `Psr\Http\Message\ResponseInterface`.
-Each middleware **SHOULD** invoke the next middleware and pass it the Request 
-object as argument.
+It can do whatever is appropriate with these objects. 
+The only hard requirement is that a middleware **MUST** return an instance of  `Psr\Http\Message\ResponseInterface`.
+Each middleware **SHOULD** invoke the next middleware and pass it the Request object as argument.
 
 ## How does middleware work?
 
-Different frameworks use middleware differently. Slim adds middleware as concentric
-layers surrounding your core application. Each new middleware layer surrounds
-any existing middleware layers. The concentric structure expands outwardly as
-additional middleware layers are added.
+Different frameworks use middleware differently. 
+Slim adds middleware as concentric layers surrounding your core application. 
+Each new middleware layer surrounds any existing middleware layers. 
+The concentric structure expands outwardly as additional middleware layers are added.
 
 The last middleware layer added is the first to be executed.
 
-When you run the Slim application, the Request object traverses the
-middleware structure from the outside in. They first enter the outermost middleware,
-then the next outermost middleware, (and so on), until they ultimately arrive
-at the Slim application itself. After the Slim application dispatches the
-appropriate route, the resultant Response object exits the Slim application and
-traverses the middleware structure from the inside out. Ultimately, a final
-Response object exits the outermost middleware, is serialized into a raw HTTP
-response, and is returned to the HTTP client. Here's a diagram that illustrates
-the middleware process flow:
+When you run the Slim application, the Request object traverses the middleware structure from the outside in. 
+They first enter the outermost middleware, then the next outermost middleware, (and so on), until they ultimately arrive at the Slim application itself. 
+After the Slim application dispatches the appropriate route, the resultant Response object exits the Slim application and traverses the middleware structure from the inside out. 
+Ultimately, a final Response object exits the outermost middleware, is serialized into a raw HTTP response, and is returned to the HTTP client. 
+Here's a diagram that illustrates the middleware process flow:
 
 <div style="padding: 2em 0; text-align: center">
     <img src="/docs/v4/images/middleware.png" alt="Middleware architecture" style="max-width: 80%;"/>
 </div>
 
 ## How do I write middleware?
 
-Middleware is a callable that accepts two arguments: a `Request` object and a `RequestHandler` object. Each middleware **MUST** return an instance of  `Psr\Http\Message\ResponseInterface`.
+Middleware is a callable that accepts two arguments: a `Request` object and a `RequestHandler` object. 
+Each middleware **MUST** return an instance of  `Psr\Http\Message\ResponseInterface`.
 
 ### Closure middleware example.
 
@@ -129,6 +126,7 @@ class ExampleBeforeMiddleware
 
 ```php
 <?php
+
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Message\ServerRequestInterface as Request;
 use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
@@ -156,6 +154,7 @@ To use these classes as a middleware, you can use **add(new ExampleMiddleware())
 
 ```php
 <?php
+
 use Slim\Factory\AppFactory;
 
 require __DIR__ . '/../vendor/autoload.php';
@@ -178,14 +177,18 @@ $app->run();
 
 ## How do I add middleware?
 
-You may add middleware to a Slim application, to an individual Slim application route or to a route group. All scenarios accept the same middleware and implement the same middleware interface.
+You may add middleware to a Slim application, to an individual Slim application route or to a route group. 
+All scenarios accept the same middleware and implement the same middleware interface.
 
 ### Application middleware
 
-Application middleware is invoked for every **incoming** HTTP request. Add application middleware with the Slim application instance's **add()** method. This example adds the Closure middleware example above:
+Application middleware is invoked for every **incoming** HTTP request. 
+Add application middleware with the Slim application instance's **add()** method. 
+This example adds the Closure middleware example above:
 
 ```php
 <?php
+
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Message\ServerRequestInterface as Request;
 use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
@@ -231,10 +234,15 @@ BEFORE Hello World AFTER
 
 ### Route middleware
 
-Route middleware is invoked _only if_ its route matches the current HTTP request method and URI. Route middleware is specified immediately after you invoke any of the Slim application's routing methods (e.g., **get()** or **post()**). Each routing method returns an instance of **\Slim\Route**, and this class provides the same middleware interface as the Slim application instance. Add middleware to a Route with the Route instance's **add()** method. This example adds the Closure middleware example above:
+Route middleware is invoked _only if_ its route matches the current HTTP request method and URI. 
+Route middleware is specified immediately after you invoke any of the Slim application's routing methods (e.g., **get()** or **post()**). 
+Each routing method returns an instance of **\Slim\Route**, and this class provides the same middleware interface as the Slim application instance. 
+Add middleware to a Route with the Route instance's **add()** method. 
+This example adds the Closure middleware example above:
 
 ```php
 <?php
+
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Message\ServerRequestInterface as Request;
 use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
@@ -268,11 +276,15 @@ Hello World
 
 ### Group middleware
 
-In addition to the overall application, and standard routes being able to accept middleware, the **group()** multi-route definition functionality, also allows individual routes internally. Route group middleware is invoked _only if_ its route matches one of the defined HTTP request methods and URIs from the group. To add middleware within the callback, and entire-group middleware to be set by chaining **add()** after the **group()** method.
+In addition to the overall application, and standard routes being able to accept middleware, the **group()** multi-route definition functionality, also allows individual routes internally. 
+Route group middleware is invoked _only if_ its route matches one of the defined HTTP request methods and URIs from the group. 
+To add middleware within the callback, and entire-group middleware to be set by chaining **add()** after the **group()** method.
+
+Sample Application, making use of callback middleware on a group of url-handlers.
 
-Sample Application, making use of callback middleware on a group of url-handlers
 ```php
 <?php
+
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Message\ServerRequestInterface as Request;
 use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
@@ -311,27 +323,26 @@ $app->group('/utils', function (RouteCollectorProxy $group) {
 $app->run();
 ```
 
-When calling the **/utils/date** method, this would output a string similar to the below
+When calling the **/utils/date** method, this would output a string similar to the below.
 
 ```bash
 It is now 2015-07-06 03:11:01. Enjoy!
 ```
 
-Visiting **/utils/time** would output a string similar to the below
+Visiting **/utils/time** would output a string similar to the below.
 
 ```bash
 It is now 1436148762. Enjoy!
 ```
 
-But visiting **/** *(domain-root)*, would be expected to generate the following output as no middleware has been assigned
+But visiting **/** *(domain-root)*, would be expected to generate the following output as no middleware has been assigned.
 
 ```bash
 Hello World
 ```
 
 ### Passing variables from middleware
-The easiest way to pass attributes from middleware is to use the request's
-attributes.
+The easiest way to pass attributes from middleware is to use the request's attributes.
 
 Setting the variable in the middleware:
 
@@ -347,7 +358,8 @@ $foo = $request->getAttribute('foo');
 
 ## Finding available middleware
 
-You may find a PSR-15 Middleware class already written that will satisfy your needs. Here are a few unofficial lists to search.
+You may find a PSR-15 Middleware class already written that will satisfy your needs. 
+Here are a few unofficial lists to search.
 
 * [Middleware for Slim Framework v4.x wiki](https://github.com/slimphp/Slim/wiki/Middleware-for-Slim-Framework-v4.x)
 * [middlewares/awesome-psr15-middlewares](https://github.com/middlewares/awesome-psr15-middlewares)