From 473d1037390d5084f308b24784de28b2c962cd54 Mon Sep 17 00:00:00 2001 From: PJ Dietz Date: Tue, 13 Mar 2018 13:12:49 -0400 Subject: [PATCH] Documentation proofreading --- docs/source/conf.py | 6 +-- docs/source/dependency-injection.rst | 2 +- docs/source/extending.rst | 2 +- docs/source/getting-started.rst | 53 ++----------------------- docs/source/handlers-and-middleware.rst | 8 ++-- docs/source/index.rst | 21 +++++----- docs/source/messages.rst | 8 ++-- docs/source/overview.rst | 4 +- docs/source/router.rst | 4 +- docs/source/uri-templates.rst | 2 +- 10 files changed, 33 insertions(+), 77 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 456bd18..541c504 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,9 +25,9 @@ master_doc = 'index' # General information about the project. project = u'WellRESTed' -copyright = u'2015, PJ Dietz' -version = '3.0.0' -release = '3.0.0' +copyright = u'2018, PJ Dietz' +version = '3.1.0' +release = '3.1.0' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/docs/source/dependency-injection.rst b/docs/source/dependency-injection.rst index f9058bb..be5d5e6 100644 --- a/docs/source/dependency-injection.rst +++ b/docs/source/dependency-injection.rst @@ -52,6 +52,6 @@ We can register the handler and these dependencies in a Pimple_ service provider } } -By "protected" the ``fooHandler`` service, we are delaying the instantiation of the ``FooHandler``, the ``Bar``, and the ``Baz`` until the handler needs to be dispatched. This works because we're not passing instance of ``FooHandler`` when we register this with a router, we're passing a function to it that does the instantiation on demand. +By "protecting" the ``fooHandler`` service, we are delaying the instantiation of the ``FooHandler``, the ``Bar``, and the ``Baz`` until the handler needs to be dispatched. This works because we're not passing instance of ``FooHandler`` when we register this with a router, we're passing a function to it that does the instantiation on demand. .. _Pimple: https://pimple.symfony.com/ diff --git a/docs/source/extending.rst b/docs/source/extending.rst index c87c172..fc56a01 100644 --- a/docs/source/extending.rst +++ b/docs/source/extending.rst @@ -140,6 +140,6 @@ Classes such as ``Server`` that create dependencies as defaults keep the instant In addition to the messages, you can do similar customization for other ``Server`` dependencies such as the dispatcher (see above), the transmitter (which writes the response out to the client), and the routers that are created with ``Server::createRouter``. These dependencies are instantiated in isolated methods as with the request and response to make this sort of customization easy, and other classes such as ``Router`` use this pattern as well. -.. _PSR-7: http://www.php-fig.org/psr/psr-7/ +.. _PSR-7: https://www.php-fig.org/psr/psr-7/ .. _Handlers and Middleware: handlers-and-middleware.html .. _Request Attributes: messages.html#attributes diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 06bc9a6..33bcbfc 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -65,8 +65,6 @@ For this, we need a router_. A router_ examines the request and sends the reques .. code-block:: php - getAttribute("name", "world"); - - // Set the response body to the greeting and the status code to 200 OK. - $response = (new Response(200)) - ->withHeader("Content-type", "text/plain") - ->withBody(new Stream("Hello, $name!")); - - // Return the response. - return $response; - } - } - - // Create middleware that will add a custom header to every response. - class CustomerHeaderMiddleware implements MiddlewareInterface + // This middleware will add a custom header to every response. + class CustomHeaderMiddleware implements MiddlewareInterface { public function process( ServerRequestInterface $request, @@ -179,7 +134,7 @@ In addition to handlers, WellRESTed also supports middlware. Middleware allows y // Delegate to the next handler in the chain to obtain a response. $response = $handler->handle($request); - // Add the header. + // Add the header to the response we got back from upstream. $response = $response->withHeader("X-example", "hello world"); // Return the altered response. @@ -192,7 +147,7 @@ In addition to handlers, WellRESTed also supports middlware. Middleware allows y // Add the header adding middleware to the server first so that it will // forward requests on to the router. - $server->add(new CustomerHeaderMiddleware()); + $server->add(new CustomHeaderMiddleware()); // Create a router to map methods and endpoints to handlers. $router = $server->createRouter(); diff --git a/docs/source/handlers-and-middleware.rst b/docs/source/handlers-and-middleware.rst index 1cebefe..7c8e5fe 100644 --- a/docs/source/handlers-and-middleware.rst +++ b/docs/source/handlers-and-middleware.rst @@ -156,10 +156,10 @@ Using Handlers and Middleware Methods that accept handlers and middleware (e.g., ``Server::add``, ``Router::register``) allow you to provide them in a number of ways. For example, you can provide an instance, a ``callable`` that provides an instance, or an ``array`` of handlers to use in sequence. The following examples will demonstrate all of the ways you can register handlers and middleware. -Factory Callable ----------------- +Factory Functions +----------------- -The best method is to use a ``callable`` that returns an instance of your handler. The main benefit of this approach is that no handlers are instantiated until they are needed. +The best method is to use a function that returns an instance of your handler. The main benefit of this approach is that no handlers are instantiated until they are needed. .. code-block:: php @@ -202,7 +202,7 @@ For handlers that do not require any arguments passed to the constructor, you ma .. code-block:: php - $router->register("GET,PUT,DELETE", "/widgets/{id}", \App\WidgetHandler::class); + $router->register("GET,PUT,DELETE", "/widgets/{id}", App\WidgetHandler::class); // ... or ... $router->register("GET,PUT,DELETE", "/widgets/{id}", 'App\\WidgetHandler'); diff --git a/docs/source/index.rst b/docs/source/index.rst index d0b868c..3956c8e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,10 +13,10 @@ Request and response messages are built to the interfaces standardized by PSR-7_ The message abstractions facilitate working with message headers, status codes, variables extracted from the path, message bodies, and all the other aspects of requests and responses. -PSR-15 Handler interfaces +PSR-15 Handler Interfaces ^^^^^^^^^^^^^^^^^^^^^^^^^ -Handlers and middleware may implement the interfaces define by the PSR-15_ standard. +WellRESTed can use handlers and middleware using the interfaces defined by the PSR-15_ standard. Router ^^^^^^ @@ -28,13 +28,12 @@ WellRESTed's router automates responding to ``OPTIONS`` requests for each endpoi Middleware ^^^^^^^^^^ -The middleware_ system allows you to build your Web service out of discrete, modular pieces. These pieces can be run in sequences where each has a chance to modify the response before handing it off to the next. For example, an authenticator can validate a request and forward it to a cache; the cache can check for a stored representation and forward to another middleware if no cached representation is found, etc. All of this happens without any one middleware needing to know anything about where it is in the chain or which middleware comes before or after. - -Most middleware is never autoloaded or instantiated until it is needed, so a Web service with hundreds of middleware still only creates instances required for the current request-response cycle. - -You can register middleware directly, register callables that return middleware (e.g., dependency container services), or register strings containing the middleware class names to autoload and instantiate on demand. +The middleware_ system allows you to build your Web service out of discrete, modular pieces. These pieces can be run in sequences where each has an opportunity to work with the request before handing it off to the next. For example, an authenticator can validate a request and forward it to a cache; the cache can check for a stored representation and forward to another middleware if no cached representation is found, etc. All of this happens without any one middleware needing to know anything about where it is in the chain or which middleware comes before or after. +Lazy Loading +^^^^^^^^^^^^ +Handlers and middleware can be registered using `factory functions`_ so that they are only instantiated if needed. This way, a Web service with hundreds of handlers and middleware still only creates instances required for the current request-response cycle. Extensible ^^^^^^^^^^ @@ -104,7 +103,7 @@ The site will also provide an ``X-example: hello world`` using dedicated middlew // Create a server $server = new Server(); - // Add the header adding middleware to the server first so that it will + // Add the header-adding middleware to the server first so that it will // forward requests on to the router. $server->add(new CustomerHeaderMiddleware()); @@ -140,7 +139,9 @@ Contents additional web-server-configuration -.. _PSR-7: http://www.php-fig.org/psr/psr-7/ -.. _PSR-15: http://www.php-fig.org/psr/psr-15/ +.. _PSR-7: https://www.php-fig.org/psr/psr-7/ +.. _PSR-15: https://www.php-fig.org/psr/psr-15/ +.. _factory functions: handlers-and-middleware.html#factory-functions +.. _middleware: handles-and-middleware.html .. _router: router.html .. _URI Templates: uri-templates.html diff --git a/docs/source/messages.rst b/docs/source/messages.rst index 60b2dfb..9bab6b8 100644 --- a/docs/source/messages.rst +++ b/docs/source/messages.rst @@ -1,7 +1,7 @@ Messages and PSR-7 ================== -WellRESTed uses PSR-7_ as the interfaces for HTTP messages. This section provides an introduction to working with these interfaces and the implementations provided with WellRESTed. For more information, please read PSR-7_. +WellRESTed uses PSR-7_ as the interfaces for HTTP messages. This section provides an introduction to working with these interfaces and the implementations provided with WellRESTed. For more information, please read about PSR-7_. Requests -------- @@ -140,7 +140,7 @@ Using a JSON representation of our cat, we can make a request like this: "color": "Calico" } -We can read and parse the JSON body, and even provide it **as** the parsedBody for later middleware or handler like this: +We can read and parse the JSON body, and even provide it as the parsedBody for later middleware or handlers like this: .. code-block:: php @@ -436,11 +436,11 @@ Each PSR-7_ message MUST have a body, so there's no ``withoutBody`` method. You ->withStatus(200) ->withBody(new \WellRESTed\Message\NullStream()); -.. _HTTP Status Code Registry: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml +.. _HTTP Status Code Registry: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml .. _PSR-7: http://www.php-fig.org/psr/psr-7/ .. _Getting Started: getting-started.html .. _Middleware: middleware.html .. _template routes: router.html#template-routes .. _regex routes: router.html#regex-routes .. _dependency injection: dependency-injection.html -.. _`php://temp`: http://php.net/manual/ro/wrappers.php.php +.. _`php://temp`: https://php.net/manual/ro/wrappers.php.php diff --git a/docs/source/overview.rst b/docs/source/overview.rst index ba9af18..fced8cc 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -4,7 +4,7 @@ Overview Installation ^^^^^^^^^^^^ -The recommended method for installing WellRESTed is to use the PHP dependency manager Composer_. Add an entry for WellRESTed in your project's ``composer.json`` file. +The recommended method for installing WellRESTed is to use Composer_. Add an entry for WellRESTed in your project's ``composer.json`` file. .. code-block:: js @@ -46,4 +46,4 @@ Licensed using the `MIT license `_. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -.. _Composer: http://getcomposer.org/ +.. _Composer: https://getcomposer.org/ diff --git a/docs/source/router.rst b/docs/source/router.rst index 6bdd9cc..a5426f2 100644 --- a/docs/source/router.rst +++ b/docs/source/router.rst @@ -83,7 +83,7 @@ For a request to ``/cats/molly``: .. code-block:: php $name = $request->getAttribute("cat"); - // molly + // "molly" Template routes are very powerful, and this only scratches the surface. See `URI Templates`_ for a full explanation of the syntax supported. @@ -341,6 +341,6 @@ Here's an example where all of the traffic beginning with ``/cats/`` is sent to $server->respond(); -.. _preg_match: http://php.net/manual/en/function.preg-match.php +.. _preg_match: https://php.net/manual/en/function.preg-match.php .. _URI Template: `URI Templates`_s .. _URI Templates: uri-templates.html diff --git a/docs/source/uri-templates.rst b/docs/source/uri-templates.rst index 84bc0c5..771aaac 100644 --- a/docs/source/uri-templates.rst +++ b/docs/source/uri-templates.rst @@ -134,6 +134,6 @@ The router will dispatch ``$pathHandler`` with for a request to ``GET /my-favori Combine the ``+`` operator and ``*`` modifier to match reserved characters as an array. For example, the template ``/{+vars*}`` will match the path ``/c@t,d*g``, providing the array ``["c@t", "d*g"]``. .. _RFC 3968 Section 2.3: https://tools.ietf.org/html/rfc3986#section-2.3 -.. _PSR-7: http://www.php-fig.org/psr/psr-7/ +.. _PSR-7: https://www.php-fig.org/psr/psr-7/ .. _RFC 6570: https://tools.ietf.org/html/rfc6570 .. _RFC 6570 Section 3.2.7: https://tools.ietf.org/html/rfc6570#section-3.2.7