alchemy / rest-bundle
Simple REST utility bundle
Installs: 87 744
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 13
Forks: 1
Open Issues: 0
Requires
- php: >=5.4
- league/fractal: ^0.12.0|^0.13.0
- willdurand/negotiation: ~2.0@dev
Requires (Dev)
- pagerfanta/pagerfanta: ^1.0.3
- phpunit/phpunit: ^4.7
- silex/silex: ^1.0.0
- squizlabs/php_codesniffer: ^2.3
- symfony/symfony: ~2.6
README
Features
- Provides automatic date parameter parsing using a predefined format and timezone
- Provides automatic sort and pagination parameter parsing
- Provides standardized error responses in AJAX/JSON contexts
Configuration
Enable the bundle by adding it to the app kernel.
By default, all listeners are enabled. You can add the following section to your config.yml
to alter the behavior
of the listeners:
Note The following configuration matches the default settings
alchemy_rest: dates: enabled: true format: Y-m-d H:i:s timezone: UTC exceptions: enabled: true content-types: [ "application/json" ] # Set this to null to use default transformer, or use the key of a service implementing # Alchemy\Rest\Response\ExceptionTransformer transformer: null sort: enabled: true sort_parameter: sort direction_parameter: dir mutli_sort_parameter: sorts pagination: enabled: true limit_parameter: limit offset_parameter: offset
Usage
Automatic date parsing
To activate date conversions on request parameters, you must explicitly define which parameters will be parsed as dates on a per-route basis in your routing files.
Example
Assuming that your requests will contain a from
and a to
parameter:
my_application.api_route: pattern: /api/route defaults: _dates: [ to, from ]
You can now type-hint your controller method as follows:
class MyController { public function index(\DateTimeInterface $from, \DateTimeInterface $to) { // Do something with those dates... } }
Automatic sort and pagination
To activate automatic sorting and pagination parameter parsing, you must explicitly activate them on a per-route basis in your routing files.
Simple example
my_application.api_route: pattern: /api/route defaults: _paginate: true _sort: true
You can now type-hint your controller method as follows:
class MyController { public function index(PaginationOptions $pagination, SortOptions $sort) { // Do something... } }
Transforming controller results into JSON responses:
This listener is always activated. To use it, you must first write a Transformer (see the League/Fractal documentation for information on transformers), and define it as a tagged service in your dependency injection configuration:
services: my_transformer: class: My\Transformer tags: - { name: alchemy_rest.transformer, alias: my_transformer }
Then in your routing file, you need to specify the transformer for a given route:
my_application.api_route: pattern: /api/route defaults: _rest: decode_request: true # Enabled by default, decodes JSON request bodies into encode_response: true transform: my_transformer list: false
You can use the list
parameter in your route defaults to specifiy whether the controller result should be handled
as a list or as a simple object. If your controller returns an instance of PagerFanta (you must include the library
in your project as it is an optional dependency), the response will automatically include a meta
property containing
a pagination
property with the pagination metadata.