Rewrite the documentation for URI Template (basic usage).
This commit is contained in:
PJ Dietz
parent
4ba6763126
commit
753e9ff33a
|
|
@ -1,12 +1,13 @@
|
|||
URI Templates
|
||||
=============
|
||||
|
||||
WellRESTed allows you to register middleware with a router using URI Templates. These templates include variables (enclosed in curly braces) which are extracted and made availble to the disptached middleware.
|
||||
WellRESTed allows you to register middleware with a router using URI Templates, based on the URI Templates defined in `RFC 6570`_. These templates include variables (enclosed in curly braces) which are extracted and made availble to the disptached middleware.
|
||||
|
||||
The URI Template syntax is based on the URI Templates defined in `RFC 6570`_.
|
||||
Reading Variables
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Example
|
||||
-------
|
||||
Basic Usage
|
||||
-----------
|
||||
|
||||
Register middleware with a URI Template by providing a path that include at least one section enclosed in curly braces. The curly braces define variables for the template.
|
||||
|
||||
|
|
@ -16,166 +17,127 @@ Register middleware with a URI Template by providing a path that include at leas
|
|||
|
||||
The router will match requests for paths like ``/widgets/12`` and ``/widgets/mega-widget`` and dispatch ``$widgetHandler`` with the extracted variables made available as request attributes.
|
||||
|
||||
To read a path variable, the ``$widgetHandler`` middleware inspects the request attribute named "id".
|
||||
To read a path variable, the ``$widgetHandler`` middleware inspects the request attribute named ``"id"``, since ``id`` is what appears inside curly braces in the URI template.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
$widgetHandler = function ($request, $response, $next) {
|
||||
|
||||
// Read the variable extracted form the path.
|
||||
$id = $request->getAttribute("id");
|
||||
// "12"
|
||||
|
||||
};
|
||||
|
||||
Syntax
|
||||
When the request path is ``/widgets/12``, the value returned by ``$request->getAttribute("id")`` is ``"12"``. For ``/widgets/mega-widget``, the value is ``"mega-widget"``.
|
||||
|
||||
.. note::
|
||||
|
||||
Request attributes are a feature of the ``ServerRequestInterface`` provided by PSR-7_.
|
||||
|
||||
Multiple Variables
|
||||
------------------
|
||||
|
||||
The example above included one variable, but URI Templates may include multiple variables. Each variable will be provided as a request attribute, so be sure to give your variables unique names.
|
||||
|
||||
Here's an example with a handful of variables. Suppose we have a template describing the path for a user's avatar image. The image is identified by a username and the image dimensions.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
$router->register("GET", "/avatars/{username}-{width}x{height}.jpg", $avatarHandlers);
|
||||
|
||||
A request for ``GET /avatars/zoidberg-100x150.jpg`` will provide these request attributes:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
$avatarHandlers = function ($request, $response, $next) {
|
||||
// Read the variables extracted form the path.
|
||||
$username = $request->getAttribute("username");
|
||||
// "zoidberg"
|
||||
$width = $request->getAttribute("width");
|
||||
// "100"
|
||||
$height = $request->getAttribute("height");
|
||||
// "150"
|
||||
};
|
||||
|
||||
Arrays
|
||||
------
|
||||
|
||||
To illustrate the syntax for various matches, we'll start by providing table of variable names and values that will be used throughout the examples.
|
||||
You may also match a comma-separated series of values as an array using a URI Template by providing a ``*`` at the end of the variable name.
|
||||
|
||||
.. class:: code-table
|
||||
.. list-table:: Variable names and values
|
||||
.. code-block:: php
|
||||
|
||||
$router->register("GET", "/favorite-colors/{colors*}", $colorsHandler);
|
||||
|
||||
A request for ``GET /favorite-colors/red,green,blue`` will provide an array as the value for the ``"colors"`` request attribute.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
$colorsHandler = function ($request, $response, $next) {
|
||||
// Read the variable extracted form the path.
|
||||
$colorsList = $request->getAttribute("colors");
|
||||
/* Array
|
||||
(
|
||||
[0] => red
|
||||
[1] => green
|
||||
[2] => blue
|
||||
)
|
||||
*/
|
||||
};
|
||||
|
||||
Matching Characters
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Unreserved Characters
|
||||
---------------------
|
||||
|
||||
By default, URI Template variables will match only "unreserved" characters. `RFC 3968 Section 2.3`_ defines unreserved characters as alphanumeric characters, ``-``, ``.``, ``_``, and ``~``. All other characters must be percent encoded to be matched by a default template variale.
|
||||
|
||||
.. note::
|
||||
|
||||
Percent-encoded characters matched by template variables are automatically decoded when provided as request attibutes.
|
||||
|
||||
Given the template ``/users/{user}``, the following paths provide these values for ``getAttribute("user")``:
|
||||
|
||||
.. list-table:: Paths and Values for the Template ``/users/{user}``
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
* - Path
|
||||
- Value
|
||||
* - empty
|
||||
- ""
|
||||
* - half
|
||||
- "50%"
|
||||
* - hello
|
||||
- "Hello, World!"
|
||||
* - path
|
||||
- "/foo/bar"
|
||||
* - var
|
||||
- "value"
|
||||
* - who
|
||||
- "fred"
|
||||
* - x
|
||||
- "1024"
|
||||
* - y
|
||||
- "768"
|
||||
* - count
|
||||
- ["one", "two", "three"]
|
||||
* - list
|
||||
- ["red", "green", "blue"]
|
||||
* - /users/123
|
||||
- "123"
|
||||
* - /users/zoidberg
|
||||
- "zoidberg"
|
||||
* - /users/zoidberg%40planetexpress.com
|
||||
- "zoidberg@planetexpress.com"
|
||||
|
||||
Simple Strings
|
||||
##############
|
||||
A request for ``GET /uses/zoidberg@planetexpress.com`` will **not** match this template, because ``@`` is not an unreserved character and is not percent encoded.
|
||||
|
||||
Variables by default match any unreserved characters. This includes all alpha-numeric characters, plus ``-``, ``.``, ``_``, and ``~``. All other characers MUST be percent encoded.
|
||||
Reserved Characters
|
||||
-------------------
|
||||
|
||||
.. class:: code-table
|
||||
.. list-table:: Simple Strings
|
||||
:header-rows: 1
|
||||
If you need to match a non-percent-encoded reserved character like ``@`` or ``/``, use the ``+`` operator at the begining of the variable name.
|
||||
|
||||
* - URI Template
|
||||
- Request Path
|
||||
* - /{var}
|
||||
- /value
|
||||
* - /{hello}
|
||||
- /Hello%20World%21
|
||||
* - /{x,hello,y}
|
||||
- /1024,Hello%20World%21,768
|
||||
Using the template ``/users/{+user}``, we can match all of the paths above, plus ``/users/zoidberg@planetexpress.com``.
|
||||
|
||||
Reserver Charaters
|
||||
##################
|
||||
Reserved matching also allows matching unencoded slashes (``/``). For example, given this template:
|
||||
|
||||
To match reserved character, begin the expression with a ``+``.
|
||||
.. code-block:: php
|
||||
|
||||
.. class:: code-table
|
||||
.. list-table:: Reserved Characters
|
||||
:header-rows: 1
|
||||
$router->register("GET", "/my-favorte-path{+path}", $pathHandler);
|
||||
|
||||
* - URI Template
|
||||
- Request Path
|
||||
* - /{+var}
|
||||
- /value
|
||||
* - /{+hello}
|
||||
- /Hello%20World!
|
||||
* - {+path}/here
|
||||
- /foo/bar/here
|
||||
The router will dispatch ``$pathHandler`` with for a request to ``GET /my-favorite-path/has/a/few/slashes.jpg``
|
||||
|
||||
Dot Prefix
|
||||
##########
|
||||
.. code-block:: php
|
||||
|
||||
Expressions beginning with ``.`` indicate that each variable matched begins with ``.``.
|
||||
$pathHandler = function ($request, $response, $next) {
|
||||
// Read the variable extracted form the path.
|
||||
$path = $request->getAttribute("path");
|
||||
// "/has/a/few/slashes.jpg"
|
||||
};
|
||||
|
||||
.. class:: code-table
|
||||
.. list-table:: Dot Prefix
|
||||
:header-rows: 1
|
||||
.. note::
|
||||
|
||||
* - URI Template
|
||||
- Request Path
|
||||
* - /{.who}
|
||||
- /.fred
|
||||
* - /{.half,who}
|
||||
- /.50%25.fred
|
||||
* - /X{.empty}
|
||||
- /X.
|
||||
|
||||
Path Segments
|
||||
#############
|
||||
|
||||
Expressions beginning with ``/`` indicate that each variable matched beings with ``/``.
|
||||
|
||||
.. class:: code-table
|
||||
.. list-table:: Path Segments
|
||||
:header-rows: 1
|
||||
|
||||
* - URI Template
|
||||
- Request Path
|
||||
* - {/who}
|
||||
- /fred
|
||||
* - {/half,who}
|
||||
- /50%25/fred
|
||||
* - {/var,empty}
|
||||
- /value/
|
||||
|
||||
Explosion
|
||||
#########
|
||||
|
||||
The explosion operator (``*``) at the end of an expression indicates that the extracted value is a list, and will be provided to the middleware as an array.
|
||||
|
||||
.. class:: code-table
|
||||
.. list-table:: Explosion
|
||||
:header-rows: 1
|
||||
|
||||
* - URI Template
|
||||
- Request Path
|
||||
* - /{count*}
|
||||
- /one,two,three
|
||||
* - {/count*}
|
||||
- /one/two/three
|
||||
* - X{.list*}
|
||||
- X.red.green.blue
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
While WellRESTed's URI templates are modeled after `RFC 6570`_, there are some parts of the RFC that WellRESTed does not implement. Some of these are because WellRESTed's uses a URI template and a given path to extract variables, whereas `RFC 6570`_ describes using a URI template and variables to create a path. Other parts are just not implemented yet, but may be in future releases.
|
||||
|
||||
Query and Fragment
|
||||
##################
|
||||
|
||||
Anything relating to the query or fragment is omitted. This is because routing is based only on the path component of the request's URI and does not make use of the query or fragment for routing purposes. Furthur, a request for a valid resource with an invalid query **should** generally result in a ``400 Bad Request`` response, not a ``404 Not Found`` response, but taking the query into account for routing would make the ``404`` response happen automatically. A developer may have reason to respond ``404`` based on the query, but this should not be the library's default behavior.
|
||||
|
||||
Path-Style Parameter Expansion
|
||||
##############################
|
||||
|
||||
`RFC 6570 Section 3.2.7`_ describes "path-style parameter expansion" where semi-colon-prefixed expressions (e.g., ``{;x,y}``) expand to key-value pairs (e.g., ``;x=1024;y=768``). This is not currently implemented in WellRESTed, although later releases may provide this functionality.
|
||||
|
||||
Variable Names
|
||||
##############
|
||||
|
||||
Variable names MUST contain only alphanumeric characters and ``_``.
|
||||
|
||||
Unique Variable Names
|
||||
#####################
|
||||
|
||||
Variables names within a given URI Template MUST be unique.
|
||||
|
||||
Although some examples in `RFC 6570`_ include the same variable name multiple times, this is not supported by WellRESTed.
|
||||
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/
|
||||
.. _RFC 6570: https://tools.ietf.org/html/rfc6570
|
||||
.. _RFC 6570 Section 3.2.7: https://tools.ietf.org/html/rfc6570#section-3.2.7
|
||||
|
|
|
|||
Loading…
Reference in New Issue