Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

some minor text tweaks and always use double `

  • Loading branch information...
commit bc755f0de2b4d81201feef0091c193970729fb1d 1 parent 3d3c8cc
@lsmith77 lsmith77 authored
Showing with 70 additions and 70 deletions.
  1. +70 −70 README.md
View
140 README.md
@@ -91,7 +91,7 @@ placing a layer between the Controller and the generation of the final output
via the templating or JMSSerializerBundle.
In your controller action you will then need to create a ``View`` instance that is then
-passed to the `fos_rest.view_handler` service for processing. The ``View`` is somewhat
+passed to the ``fos_rest.view_handler`` service for processing. The ``View`` is somewhat
modeled after the ``Response`` class, but as just stated it simply works as a container
for all the data/configuration for the ``ViewHandler`` class for this particular action.
So the ``View`` instance must always be processed by a ``ViewHandler`` (see the below
@@ -126,20 +126,20 @@ https://github.com/liip/LiipHelloBundle/blob/master/Controller/HelloController.p
### Configuration
-The `formats` and `templating_formats` settings determine which formats are supported via
+The ``formats`` and ``templating_formats`` settings determine which formats are supported via
the serializer and which via the template layer. Note that a value of ``false`` means
that the given format is disabled. In other words any format listed in ``templating_formats``
will require a template for rendering using the ``templating`` service, will any format
listed in ``formats`` will use JMSSerializerBundle for rendering.
-When using `RouteRedirectView::create()` the default behavior of forcing a redirect to the
+When using ``RouteRedirectView::create()`` the default behavior of forcing a redirect to the
route for html is enabled, but needs to be enabled for other formats if needed.
-Finally the HTTP response status code for failed validation is defaults to `400`. Note when
-changing the default you can use name constants of `FOS\RestBundle\Response\Codes` class or
+Finally the HTTP response status code for failed validation is defaults to ``400``. Note when
+changing the default you can use name constants of ``FOS\RestBundle\Response\Codes`` class or
an integer status code.
-You can also set the default templating engine so something different than the default of `twig`:
+You can also set the default templating engine so something different than the default of ``twig``:
```yaml
# app/config/config.yml
@@ -256,7 +256,7 @@ fos_rest:
The view response listener makes it possible to simply return a ``View`` instance from action
controllers. The final output will then automatically be processed via the listener by the
-`fos_rest.view_handler` service.
+`fos_rest.view_handler`` service.
This requires adding the SensioFrameworkExtraBundle to your vendors:
@@ -333,7 +333,7 @@ in order to populate the "request" parameter bag of the Request. This for exampl
sending data that normally would be send via POST as ``application/x-www-form-urlencode``
in a different format (for example application/json) as a PUT.
-You can add a decoder for the custom format or replace decoder service for `json` or `xml`
+You can add a decoder for the custom format or replace decoder service for ``json`` or ``xml``
format. Below you can see how to override the decoder of json format:
```yaml
@@ -363,7 +363,7 @@ are no more Accept headers to check. In this case ``fallback_format`` is used.
Note that if ``_format`` is matched inside the route, then a virtual Accept header setting is
added with a ``q`` setting one lower than the lowest Accept header, meaning that format is
-checked for a match in the priorities last. If ``prefer_extension`` is set to ``true` then
+checked for a match in the priorities last. If ``prefer_extension`` is set to ``true`` then
the virtual Accept header will be one higher than the highest ``q`` causing the extension
to be checked first.
@@ -407,8 +407,8 @@ ExceptionController support
Using this custom ExceptionController it is possible to leverage the View layer
when building responses for uncaught Exceptions.
-To enable the RestBundle view-layer-aware ExceptionController update the framework
-section of your config like this:
+To enable the RestBundle view-layer-aware ExceptionController update the twig
+section of your config as follows:
```yaml
# app/config/config.yml
@@ -416,9 +416,9 @@ twig:
exception_controller: 'FOS\RestBundle\Controller\ExceptionController::showAction'
```
-To map Exception classes to HTTP response status codes an `exception_map` may be configured,
+To map Exception classes to HTTP response status codes an ``exception_map`` may be configured,
where the keys match a fully qualified class name and the values are either an integer HTTP response
-status code or a string matching a class constant of the `FOS\RestBundle\Response\Codes` class:
+status code or a string matching a class constant of the ``FOS\RestBundle\Response\Codes`` class:
```yaml
# app/config/config.yml
@@ -432,7 +432,7 @@ fos_rest:
```
If you want to display the message from the exception in the content of the response, add the
-exception to the messages map as well. If not only the statuscode will be returned.
+exception to the messages map as well. If not only the status code will be returned.
If you know what status code you want to return you do not have to add a mapping, you can do
this in your controller:
@@ -460,7 +460,7 @@ The RestBundle provides custom route loaders to help in defining REST friendly r
as well as reducing the manual work of configuring routes and the given requirements
(like making sure that only GET may be used in certain routes etc.).
-You may specify a `default_format` that the routing loader will use for the `_format`
+You may specify a ``default_format`` that the routing loader will use for the ``_format``
parameter if none is specified.
```yaml
@@ -483,8 +483,8 @@ users:
resource: Acme\HelloBundle\Controller\UsersController
```
-This will tell Symfony2 to automatically generate proper REST routes from your `UsersController` action names.
-Notice `type: rest` option. It's required so that the RestBundle can find which routes are supported.
+This will tell Symfony2 to automatically generate proper REST routes from your ``UsersController`` action names.
+Notice ``type: rest`` option. It's required so that the RestBundle can find which routes are supported.
## Define resource actions
@@ -493,67 +493,67 @@ Notice `type: rest` option. It's required so that the RestBundle can find which
class UsersController extends Controller
{
public function getUsersAction()
- {} // `get_users` [GET] /users
+ {} // ``get_users`` [GET] /users
public function newUsersAction()
- {} // `new_users` [GET] /users/new
+ {} // ``new_users`` [GET] /users/new
public function postUsersAction()
- {} // `post_users` [POST] /users
+ {} // ``post_users`` [POST] /users
public function patchUsersAction()
- {} // `patch_users` [PATCH] /users
+ {} // ``patch_users`` [PATCH] /users
public function getUserAction($slug)
- {} // `get_user` [GET] /users/{slug}
+ {} // ``get_user`` [GET] /users/{slug}
public function editUserAction($slug)
- {} // `edit_user` [GET] /users/{slug}/edit
+ {} // ``edit_user`` [GET] /users/{slug}/edit
public function putUserAction($slug)
- {} // `put_user` [PUT] /users/{slug}
+ {} // ``put_user`` [PUT] /users/{slug}
public function patchUserAction($slug)
- {} // `patch_user` [PATCH] /users/{slug}
+ {} // ``patch_user`` [PATCH] /users/{slug}
public function lockUserAction($slug)
- {} // `lock_user` [PUT] /users/{slug}/lock
+ {} // ``lock_user`` [PUT] /users/{slug}/lock
public function banUserAction($slug, $id)
- {} // `ban_user` [PUT] /users/{slug}/ban
+ {} // ``ban_user`` [PUT] /users/{slug}/ban
public function removeUserAction($slug)
- {} // `remove_user` [GET] /users/{slug}/remove
+ {} // ``remove_user`` [GET] /users/{slug}/remove
public function deleteUserAction($slug)
- {} // `delete_user` [DELETE] /users/{slug}
+ {} // ``delete_user`` [DELETE] /users/{slug}
public function getUserCommentsAction($slug)
- {} // `get_user_comments` [GET] /users/{slug}/comments
+ {} // ``get_user_comments`` [GET] /users/{slug}/comments
public function newUserCommentsAction($slug)
- {} // `new_user_comments` [GET] /users/{slug}/comments/new
+ {} // ``new_user_comments`` [GET] /users/{slug}/comments/new
public function postUserCommentsAction($slug)
- {} // `post_user_comments` [POST] /users/{slug}/comments
+ {} // ``post_user_comments`` [POST] /users/{slug}/comments
public function getUserCommentAction($slug, $id)
- {} // `get_user_comment` [GET] /users/{slug}/comments/{id}
+ {} // ``get_user_comment`` [GET] /users/{slug}/comments/{id}
public function editUserCommentAction($slug, $id)
- {} // `edit_user_comment` [GET] /users/{slug}/comments/{id}/edit
+ {} // ``edit_user_comment`` [GET] /users/{slug}/comments/{id}/edit
public function putUserCommentAction($slug, $id)
- {} // `put_user_comment` [PUT] /users/{slug}/comments/{id}
+ {} // ``put_user_comment`` [PUT] /users/{slug}/comments/{id}
public function voteUserCommentAction($slug, $id)
- {} // `vote_user_comment` [PUT] /users/{slug}/comments/{id}/vote
+ {} // ``vote_user_comment`` [PUT] /users/{slug}/comments/{id}/vote
public function removeUserCommentAction($slug, $id)
- {} // `remove_user_comment` [GET] /users/{slug}/comments/{id}/remove
+ {} // ``remove_user_comment`` [GET] /users/{slug}/comments/{id}/remove
public function deleteUserCommentAction($slug, $id)
- {} // `delete_user_comment` [DELETE] /users/{slug}/comments/{id}
+ {} // ``delete_user_comment`` [DELETE] /users/{slug}/comments/{id}
}
```
@@ -565,18 +565,18 @@ as shown in the comments in the above example. Here are a few things to note:
There are 5 actions that have special meaning in regards to REST and have the following behavior:
* **get** - this action accepts *GET* requests to the url */resources* and returns all resources for this type. Shown as
-`UsersController::getUsersAction()` above. This action also accepts *GET* requests to the url */resources/{id}* and
-returns a single resource for this type. Shown as `UsersController::getUserAction()` above.
+`UsersController::getUsersAction()`` above. This action also accepts *GET* requests to the url */resources/{id}* and
+returns a single resource for this type. Shown as ``UsersController::getUserAction()`` above.
* **post** - this action accepts *POST* requests to the url */resources* and creates a new resource of this type. Shown
-as `UsersController::postUsersAction()` above.
+as ``UsersController::postUsersAction()`` above.
* **put** - this action accepts *PUT* requests to the url */resources/{id}* and updates a single resource for this type.
-Shown as `UsersController::putUserAction()` above.
+Shown as ``UsersController::putUserAction()`` above.
* **delete** - this action accepts *DELETE* requests to the url */resources/{id}* and deltes a single resource for this
-type. Shown as `UsersController::deleteUserAction()` above.
+type. Shown as ``UsersController::deleteUserAction()`` above.
* **patch** - this action accepts *PATCH* requests to the url */resources* and is supposed to partially modify collection
-of resources (e.g. apply batch modifications to subset of resources). Shown as `UsersController::patchUsersAction()` above.
+of resources (e.g. apply batch modifications to subset of resources). Shown as ``UsersController::patchUsersAction()`` above.
This action also accepts *PATCH* requests to the url */resources/{id}* and is supposed to partially modify the resource.
-Shown as `UsersController::patchUserAction()` above.
+Shown as ``UsersController::patchUserAction()`` above.
### Conventional Actions
@@ -585,24 +585,24 @@ REST service with hypertext - most commonly through an HTML page. There are 3 Co
supported by this bundle:
* **new** - A hypermedia representation that acts as the engine to *POST*. Typically this is a form that allows the client
-to *POST* a new resource. Shown as `UsersController::newUsersAction()` above.
+to *POST* a new resource. Shown as ``UsersController::newUsersAction()`` above.
* **edit** - A hypermedia representation that acts as the engine to *PUT*. Typically this is a form that allows the client
-to *PUT*, or update, an existing resource. Shown as `UsersController::editUserAction()` above.
+to *PUT*, or update, an existing resource. Shown as ``UsersController::editUserAction()`` above.
* **remove** - A hypermedia representation that acts as the engine to *DELETE*. Typically this is a form that allows the
-client to *DELETE* an existing resource. Commonly a confirmation form. Shown as `UsersController::removeUserAction()` above.
+client to *DELETE* an existing resource. Commonly a confirmation form. Shown as ``UsersController::removeUserAction()`` above.
### Custom PUT Actions
All actions that do not match the ones listed in the sections above will register as a *PUT* action. In the controller
-shown above, these actions are `UsersController::lockUserAction()` and `UsersController::banUserAction()`. You could
-just as easily create a method called `UsersController::promoteUserAction()` which would take a *PUT* request to the url
+shown above, these actions are ``UsersController::lockUserAction()`` and ``UsersController::banUserAction()`. You could
+just as easily create a method called ``UsersController::promoteUserAction()`` which would take a *PUT* request to the url
*/users/{slug}/promote*. This allows for easy updating of aspects of a resource, without having to deal with the
resource as a whole at the standard *PUT* endpoint.
### Sub-Resource Actions
Of course it's possible and common to have sub or child resources. They are easily defined within the same controller by
-following the naming convention `ResourceController::actionResourceSubResource()` - as seen in the example above with
+following the naming convention ``ResourceController::actionResourceSubResource()`` - as seen in the example above with
`UsersController::getUserCommentsAction()`. This is a good strategy to follow when the child resource needs the parent
resource's ID in order to look up itself.
@@ -628,16 +628,16 @@ comments:
resource: "@AcmeHello\Controller\CommentsController"
```
-Notice `parent: users` option in the second case. This option specifies that the comments resource
-is child of the users resource. In this case, your `UsersController` MUST always have a single
-resource `get...` action:
+Notice ``parent: users`` option in the second case. This option specifies that the comments resource
+is child of the users resource. In this case, your ``UsersController`` MUST always have a single
+resource ``get...`` action:
```php
<?php
class UsersController extends Controller
{
public function getUserAction($slug)
- {} // `get_user` [GET] /users/{slug}
+ {} // ``get_user`` [GET] /users/{slug}
...
}
@@ -648,42 +648,42 @@ auto-generation process and can be any name you like.
## Define child resource controller
-`CommentsController` actions now will looks like:
+`CommentsController`` actions now will looks like:
```php
<?php
class CommentsController extends Controller
{
public function voteCommentAction($slug, $id)
- {} // `vote_user_comment` [PUT] /users/{slug}/comments/{id}/vote
+ {} // ``vote_user_comment`` [PUT] /users/{slug}/comments/{id}/vote
public function getCommentsAction($slug)
- {} // `get_user_comments` [GET] /users/{slug}/comments
+ {} // ``get_user_comments`` [GET] /users/{slug}/comments
public function getCommentAction($slug, $id)
- {} // `get_user_comment` [GET] /users/{slug}/comments/{id}
+ {} // ``get_user_comment`` [GET] /users/{slug}/comments/{id}
public function deleteCommentAction($slug, $id)
- {} // `delete_user_comment` [DELETE] /users/{slug}/comments/{id}
+ {} // ``delete_user_comment`` [DELETE] /users/{slug}/comments/{id}
public function newCommentsAction($slug)
- {} // `new_user_comments` [GET] /users/{slug}/comments/new
+ {} // ``new_user_comments`` [GET] /users/{slug}/comments/new
public function editCommentAction($slug, $id)
- {} // `edit_user_comment` [GET] /users/{slug}/comments/{id}/edit
+ {} // ``edit_user_comment`` [GET] /users/{slug}/comments/{id}/edit
public function removeCommentAction($slug, $id)
- {} // `remove_user_comment` [GET] /users/{slug}/comments/{id}/remove
+ {} // ``remove_user_comment`` [GET] /users/{slug}/comments/{id}/remove
}
```
-Notice, we got rid of the `User` part in action names. That is because the RestBundle routing
-already knows, that `CommentsController::...` is child resources of `UsersController::getUser()`
+Notice, we got rid of the ``User`` part in action names. That is because the RestBundle routing
+already knows, that ``CommentsController::...`` is child resources of ``UsersController::getUser()``
resource.
## Include resource collections in application routing
-Last step is mapping of your collection routes into the application `routing.yml`:
+Last step is mapping of your collection routes into the application ``routing.yml``:
```yaml
# app/config/routing.yml
@@ -692,10 +692,10 @@ users:
resource: "@AcmeHello/Resources/config/users_routes.yml"
```
-That's all. Note that it's important to use the `type: rest` param when including your application's
+That's all. Note that it's important to use the ``type: rest`` param when including your application's
routing file. Without it, rest routes will still work but resource collections will fail. If you get an
-exception that contains `...routing loader does not support given key: "parent"...` then you are most likely missing
-the `type: rest` param in your application level routes include.
+exception that contains ...routing loader does not support given key: "parent"... then you are most likely missing
+the ``type: rest`` param in your application level routes include.
## Routes naming
@@ -712,7 +712,7 @@ For further examples, see comments of controllers in the code above.
### Naming collisions
Sometimes, routes auto-naming will lead to route names collisions, so RestBundle route
-collections provides a `name_prefix` (`name-prefix` for xml and @NamePrefix for
+collections provides a ``name_prefix`` (``name-prefix`` for xml and @NamePrefix for
annotations) parameter:
```yaml
Please sign in to comment.
Something went wrong with that request. Please try again.