Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

Commit 06c6b91

Browse files
lsmith77lsmith77
committed
Merge pull request #355 from symfony-cmf/exposing_content_via_rest
initial commit of a cookbook entry for how to setup REST read support
2 parents 97f43ef + 25a3d23 commit 06c6b91

File tree

3 files changed

+169
-0
lines changed

3 files changed

+169
-0
lines changed

‎cookbook/exposing_content_via_rest.rst

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
.. index::
2+
single: Tutorial, REST
3+
single: ContentBundle
4+
5+
Exposing Content via REST
6+
=========================
7+
8+
Many applications need to expose content via REST APIs to partners or to
9+
enable integration into other applications. As the CMF is build on top
10+
of Symfony2, it's possible to leverage many of the available bundles to
11+
provide a REST API for content stored in the CMF. This cookbook will
12+
detail how to provide a read API using the following bundles:
13+
14+
* :doc:`Cmf ContentBundle <../bundles/content/index>`;
15+
* `FOSRestBundle`_;
16+
* `JMSSerializerBundle`_.
17+
18+
It is assumed that you have:
19+
20+
* A working knowledge of the Symfony2 CMF framework;
21+
* An application with the ContentBundle setup.
22+
23+
Installation
24+
------------
25+
26+
The ContentBundle provides support for the `FOSRestBundle view layer`_,
27+
which is automatically activated by the ``ContentController`` when the
28+
bundle is available. Furthermore, the FOSRestBundle needs a serializer
29+
to generate the REST output. The best choice is the JMSSerializerBundle:
30+
31+
.. code-block:: javascript
32+
33+
{
34+
..
35+
"require": {
36+
..
37+
"friendsofsymfony/rest-bundle": "1.0.*",
38+
"jms/serializer-bundle": "0.13.*",
39+
}
40+
}
41+
42+
.. note::
43+
44+
Both bundles are already required by the CreateBundle.
45+
46+
.. caution::
47+
48+
When using PHPCR-ODM it is necessary to require at least version 1.0.1
49+
of ``doctrine\phpcr-odm``.
50+
51+
Then use Composer_ to update your projects vendors:
52+
53+
.. code-block:: bash
54+
55+
$ php composer.phar update
56+
57+
Configuring FOSRestBundle
58+
-------------------------
59+
60+
Here is an example configuration for the FOSRestBundle.
61+
62+
.. configuration-block::
63+
64+
.. code-block:: yaml
65+
66+
fos_rest:
67+
# configure the view handler
68+
view:
69+
force_redirects:
70+
html: true
71+
formats:
72+
json: true
73+
xml: true
74+
templating_formats:
75+
html: true
76+
# add a content negotiation rule, enabling support for json/xml for the entire website
77+
format_listener:
78+
rules:
79+
- { path: ^/, priorities: [ html, json, xml ], fallback_format: html, prefer_extension: false }
80+
81+
.. code-block:: xml
82+
83+
<?xml version="1.0" encoding="UTF-8" ?>
84+
<container xmlns="http://symfony.com/schema/dic/services">
85+
86+
<config xmlns="http://example.org/schema/dic/fos_rest">
87+
<!-- configure the view handler -->
88+
<view>
89+
<force-redirect name="html">true</force-redirect>
90+
91+
<format name="json">true</format>
92+
<format name="xml">true</format>
93+
94+
<templating-format name="html">true</templating-format>
95+
</view>
96+
97+
<!-- add a content negotiation rule, enabling support for json/xml for the entire website -->
98+
<format-listener>
99+
<rule path="^/"
100+
fallback-format="html"
101+
prefer-extension="false"
102+
priorities="html,json,xml"
103+
/>
104+
</format-listener>
105+
</config>
106+
</container>
107+
108+
.. code-block:: php
109+
110+
$container->loadFromExtension('fos_rest', array(
111+
// configure the view handler
112+
'view' => array(
113+
'force_redirects' => array(
114+
'html' => true,
115+
),
116+
'formats' => array(
117+
'json' => true,
118+
'xml' => true,
119+
),
120+
'templating_formats' => array(
121+
'html' => true,
122+
),
123+
),
124+
// add a content negotiation rule, enabling support for json/xml for the entire website
125+
'format_listener' => array(
126+
'rules' => array(
127+
array(
128+
'path' => '^/',
129+
'priorities' => array('html', 'json', 'xml'),
130+
'fallback_format' => 'html',
131+
'prefer_extension' => false,
132+
),
133+
),
134+
),
135+
));
136+
137+
Using the REST API
138+
------------------
139+
140+
After you configured the FOSRestBundle, you need to execute the following
141+
commands:
142+
143+
.. code-block:: bash
144+
145+
curl http://my-cmf.org/app_dev.php -H Accept:application/json
146+
curl http://my-cmf.org/app_dev.php -H Accept:application/xml
147+
curl http://my-cmf.org/app_dev.php -H Accept:text/html
148+
149+
This is all it takes to enable read support via JSON or XML!
150+
151+
The JMS serializer comes with sense defaults for Doctrine object mappers.
152+
However it might be necessary to add additional mapping to more tightly
153+
control what gets exposed. See the `documentation of the JMS serializer`_
154+
for details.
155+
156+
.. note::
157+
158+
The `default response format changed between 1.0 and 1.1 of the ContentBundle`_.
159+
In 1.0 the response is wrapped inside an array/tag. This is no longer the
160+
case in 1.1
161+
162+
.. _`FOSRestBundle`: https://github.com/FriendsOfSymfony/FOSRestBundle
163+
.. _`JMSSerializerBundle`: https://github.com/schmittjoh/JMSSerializerBundle
164+
.. _`FOSRestBundle view layer`: https://github.com/FriendsOfSymfony/FOSRestBundle/blob/master/Resources/doc/2-the-view-layer.md
165+
.. _Composer: http://getcomposer.org/
166+
.. _`documentation of the JMS serializer`: http://jmsyst.com/libs/#serializer
167+
.. _`default response format changed between 1.0 and 1.1 of the ContentBundle`: https://github.com/symfony-cmf/ContentBundle/pull/91

‎cookbook/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,6 @@ The Cookbook
1313
creating_cms_using_cmf_and_sonata
1414
using_blockbundle_and_contentbundle
1515
handling_multilang_documents
16+
exposing_content_via_rest
1617

1718
.. include:: map.rst.inc

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@
1313
* :doc:`creating_cms_using_cmf_and_sonata`
1414
* :doc:`using_blockbundle_and_contentbundle`
1515
* :doc:`handling_multilang_documents`
16+
* :doc:`exposing_content_via_rest`

0 commit comments

Comments
 (0)