10000 Merge branch '2.0' · lazymanc/symfony-docs@da3938b · GitHub
[go: up one dir, main page]
Skip to content

Commit da3938b

Browse files
weaverryanweaverryan
committed
Merge branch '2.0'
Conflicts: reference/constraints/Image.rst
2 parents 10471ae + 4e85d2b commit da3938b

File tree

11 files changed

+262
-13
lines changed

11 files changed

+262
-13
lines changed

‎book/http_fundamentals.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ ideas from many technologies: the tools and concepts you're about to learn
1313
represent the efforts of thousands of people, over many years. In other words,
1414
you're not just learning "Symfony", you're learning the fundamentals of the
1515
web, development best practices, and how to use many amazing new PHP libraries,
16-
inside or independent of Symfony2. So, get ready.
16+
inside or independently of Symfony2. So, get ready.
1717

1818
True to the Symfony2 philosophy, this chapter begins by explaining the fundamental
1919
concept common to web development: HTTP. Regardless of your background or
@@ -298,7 +298,7 @@ and create the appropriate response based on your application logic*.
298298

299299
The ``Request`` and ``Response`` classes are part of a standalone component
300300
included with Symfony called ``HttpFoundation``. This component can be
301-
used entirely independent of Symfony and also provides classes for handling
301+
used entirely independently of Symfony and also provides classes for handling
302302
sessions and file uploads.
303303

304304
The Journey from the Request to the Response
@@ -351,7 +351,7 @@ file that handles every request coming into your application. For example:
351351
the URLs can easily be cleaned up to be just ``/``, ``/contact`` and
352352
``/blog``.
353353

354-
Now, every request is handled exactly the same. Instead of individual URLs
354+
Now, every request is handled exactly the same way. Instead of individual URLs
355355
executing different PHP files, the front controller is *always* executed,
356356
and the routing of different URLs to different parts of your application
357357
is done internally. This solves both problems with the original approach.

‎contributing/code/standards.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ follow the same guidelines, and you should too.
99
Remember that the main advantage of standards is that every piece of code
1010
looks and feels familiar, it's not about this or that being more readable.
1111

12-
Symfony follows the standards defined in the PSR-0, PSR-1, and PSR-2
12+
Symfony follows the standards defined in the `PSR-0`_, `PSR-1`_ and `PSR-2`_
1313
documents.
1414

1515
Since a picture - or some code - is worth a thousand words, here's a short
@@ -63,7 +63,7 @@ example containing most features described below:
6363
} else {
6464
$dummy = ucwords($dummy);
6565
}
66-
}
66+
}
6767
6868
return $dummy;
6969
}
@@ -121,3 +121,7 @@ License
121121

122122
* Symfony is released under the MIT license, and the license block has to be
123123
present at the top of every PHP file, before the namespace.
124+
125+
.. _`PSR-0`: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
126+
.. _`PSR-1`: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md
127+
.. _`PSR-2`: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

‎cookbook/bundles/override.rst

Lines changed: 66 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,61 @@ inheritance. For more information, see :doc:`/cookbook/bundles/inheritance`.
3535
Services & Configuration
3636
------------------------
3737

38-
In progress...
38+
In order to override/extend a service, there are two options. First, you can
39+
set the parameter holding the service's class name to your own class by setting
40+
it in ``app/config/config.yml``. This of course is only possible if the class name is
41+
defined as a parameter in the service config of the bundle containing the
42+
service. For example, to override the class used for Symfony's ``translator``
43+
service, you would override the ``translator.class`` parameter. Knowing exactly
44+
which parameter to override may take some research. For the translator, the
45+
parameter is defined and used in the ``Resources/config/translation.xml`` file
46+
in the core FrameworkBundle:
47+
48+
.. configuration-block::
49+
50+
.. code-block:: yaml
51+
52+
# app/config/config.yml
53+
parameters:
54+
translator.class: Acme\HelloBundle\Translation\Translator
55+
56+
.. code-block:: xml
57+
58+
<!-- app/config/config.xml -->
59+
<parameters>
60+
<parameter key="translator.class">Acme\HelloBundle\Translation\Translator</parameter>
61+
</parameters>
62+
63+
.. code-block:: php
64+
65+
// app/config/config.php
66+
67+
$container->setParameter('translator.class', 'Acme\HelloBundle\Translation\Translator');
68+
69+
Secondly, if the class is not available as a parameter, you want to make sure the
70+
class is always overridden when your bundle is used, or you need to modify
71+
something beyond just the class name, you should use a compiler pass::
72+
73+
namespace Foo\BarBundle\DependencyInjection\Compiler;
74+
75+
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
76+
use Symfony\Component\DependencyInjection\ContainerBuilder;
77+
78+
class OverrideServiceCompilerPass implements CompilerPassInterface
79+
{
80+
public function process(ContainerBuilder $container)
81+
{
82+
$definition = $container->getDefinition('original-service-id');
83+
$definition->setClass('Foo\BarBundle\YourService');
84+
}
85+
}
86+
87+
In this example we fetch the service definition of the original service, and set
88+
its class name to our own class.
89+
90+
See :doc:`/cookbook/service_container/compiler_passes` for information on how to use
91+
compiler passes. If you want to do something beyond just overriding the class -
92+
like adding a method call - you can only use the compiler pass method.
3993

4094
Entities & Entity mapping
4195
-------------------------
@@ -45,7 +99,17 @@ In progress...
4599
Forms
46100
-----
47101

48-
In progress...
102+
In order to override a form type, it has to be registered as a service (meaning
103+
it is tagged as "form.type"). You can then override it as you would override any
104+
service as explained in `Services & Configuration`_. This, of course, will only
105+
work if the type is referred to by its alias rather than being instantiated,
106+
e.g.::
107+
108+
$builder->add('name', 'custom_type');
109+
110+
rather than::
111+
112+
$builder->add('name', new CustomType());
49113

50114
Validation metadata
51115
-------------------

‎cookbook/controller/error_pages.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ end-user, create a new template located at
5858

5959
In addition to the standard HTML error page, Symfony provides a default error
6060
page for many of the most common response formats, including JSON
61-
(``error.json.twig``), XML, (``error.xml.twig``), and even Javascript
61+
(``error.json.twig``), XML (``error.xml.twig``) and even Javascript
6262
(``error.js.twig``), to name a few. To override any of these templates, just
6363
create a new file with the same name in the
6464
``app/Resources/TwigBundle/views/Exception`` directory. This is the standard

‎cookbook/event_dispatcher/before_after_filters.rst

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
.. index::
2+
single: Event Dispatcher
3+
4+
How to setup before and after Filters
5+
=====================================
6+
7+
It is quite common in web application development to need some logic to be
8+
executed just before or just after your controller actions acting as filters
9+
or hooks.
10+
11+
In Symfony1, this was achieved with the preExecute and postExecute methods,
12+
most major frameworks have similar methods but there is no such thing in Symfony2.
13+
The good news is that there is a much better way to interfere the
14+
Request -> Response process using the EventDispatcher component.
15+
16+
Token validation Example
17+
------------------------
18+
19+
Imagine that you need to develop an API where some controllers are public
20+
but some others are restricted to one or some clients. For these private features,
21+
you might provide a token to your clients to identify themselves.
22+
23+
So, before executing your controller action, you need to check if the action
24+
is restricted or not. And if it is restricted, you need to validate the provided
25+
token.
26+
27+
.. note::
28+
29+
Please note that for simplicity in the recipe, tokens will be defined
30+
in config and neither database setup nor authentication provider via
31+
the Security component will be used.
32+
33+
Creating a before filter with a controller.request event
34+
--------------------------------------------------------
35+
36+
Basic Setup
37+
~~~~~~~~~~~
38+
39+
You can add basic token configuration using ``config.yml`` and the parameters key:
40+
41+
.. configuration-block::
42+
43+
.. code-block:: yaml
44+
45+
# app/config/config.yml
46+
parameters:
47+
tokens:
48+
client1: pass1
49+
client2: pass2
50+
51+
.. code-block:: xml
52+
53+
<!-- app/config/config.xml -->
54+
<parameters>
55+
<parameter key="tokens" type="collection">
56+
<parameter key="client1">pass1</parameter>
57+
<parameter key="client2">pass2</parameter>
58+
</parameter>
59+
</parameters>
60+
61+
.. code-block:: php
62+
63+
// app/config/config.php
64+
$container->setParameter('tokens', array(
65+
'client1' => 'pass1',
66+
'client2' => 'pass2'
67+
));
68+
69+
Tag Controllers to be checked
70+
-----------------------------
71+
72+
A ``kernel.controller`` listener gets notified on every request, right before
73+
the controller is executed. First, you need some way to identify if the controller
74+
that matches the request needs token validation.
75+
76+
A clean and easy way is to create an empty interface and make the controllers
77+
implement it::
78+
79+
namespace Acme\DemoBundle\Controller;
80+
81+
interface TokenAuthenticatedController
82+
{
83+
// Nothing here
84+
}
85+
86+
A controller that implements this interface simply looks like this::
87+
88+
class FooController implements TokenAuthenticatedController
89+
{
90+
// Your actions that need authentication
91+
}
92+
93+
Creating an Event Listener
94+
--------------------------
95+
96+
Next, you'll need to create an event listener, which will hold the logic
97+
that you want executed before your controllers. If you're not familiar with
98+
event listeners, you can learn more about them at :doc:`/cookbook/service_container/event_listener`::
99+
100+
namespace Acme\DemoBundle\EventListener;
101+
102+
use Acme\DemoBundle\Controller\TokenAuthenticatedController;
103+
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
104+
use Symfony\Component\HttpKernel\Event\FilterControllerEvent;
105+
106+
class BeforeListener
107+
{
108+
private $tokens;
109+
110+
public function __contruct($tokens)
111+
{
112+
$this->tokens = $tokens;
113+
}
114+
115+
public function onKernelController(FilterControllerEvent $event)
116+
{
117+
$controller = $event->getController();
118+
119+
/*
120+
* $controller passed can be either a class or a Closure. This is not usual in Symfony2 but it may happen.
121+
* If it is a class, it comes in array format
122+
*/
123+
if (!is_array($controller)) {
124+
return;
125+
}
126+
127+
if($controller[0] instanceof TokenAuthenticatedController) {
128+
$token = $event->getRequest()->get('token');
129+
if (!in_array($token, $this->tokens)) {
130+
throw new AccessDeniedHttpException('This action needs a valid token!');
131+
}
132+
}
133+
}
134+
}
135+
136+
Registering the Listener
137+
------------------------
138+
139+
Finally, register your listener as a service and tag it as an event listener.
140+
By listening on ``kernel.controller``, you're telling Symfony that you want
141+
your listener to be called just before any controller is executed:
142+
143+
.. configuration-block::
144+
145+
.. code-block:: yaml
146+
147+
# app/config/config.yml (or inside or your services.yml)
148+
services:
149+
demo.tokens.action_listener:
150+
class: Acme\DemoBundle\EventListener\BeforeListener
151+
arguments: [ %tokens% ]
152+
tags:
153+
- { name: kernel.event_listener, event: kernel.controller, method: onKernelController }
154+
155+
.. code-block:: xml
156+
157+
<service id="demo.tokens.action_listener" class="Acme\DemoBundle\EventListener\BeforeListener">
158+
<argument>%tokens%</argument>
159+
<tag name="kernel.event_listener" event="kernel.controller" method="onKernelController" />
160+
</service>
161+
162+
.. code-block:: php
163+
164+
use Symfony\Component\DependencyInjection\Definition;
165+
166+
$listener = new Definition('Acme\DemoBundle\EventListener\BeforeListener', array('%tokens%'));
167+
$listener->addTag('kernel.event_listener', array('event' => 'kernel.controller', 'method' => 'onKernelController'));
168+
$container->setDefinition('demo.tokens.action_listener', $listener);
169+

‎cookbook/event_dispatcher/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Event Dispatcher
44
.. toctree::
55
:maxdepth: 2
66

7+
before_after_filters
78
class_extension
89
method_behavior
910

‎cookbook/form/form_customization.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,7 @@ Referencing Base Form Blocks (Twig specific)
342342

343343
So far, to override a particular form block, the best method is to copy
344344
the default block from `form_div_layout.html.twig`_, paste it into a different template,
345-
and the customize it. In many cases, you can avoid doing this by referencing
345+
and then customize it. In many cases, you can avoid doing this by referencing
346346
the base block when customizing it.
347347

348348
This is easy to do, but varies slightly depending on if your form block customizations
@@ -922,4 +922,4 @@ To render a help message below a field, pass in a ``help`` variable:
922922
.. tip::
923923
See :ref:`cookbook-form-theming-methods` for how to apply this customization.
924924

925-
.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
925+
.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@
5151

5252
* :doc:`/cookbook/event_dispatcher/index`
5353

54+
* :doc:`/cookbook/event_dispatcher/before_after_filters`
5455
* :doc:`/cookbook/event_dispatcher/class_extension`
5556
* :doc:`/cookbook/event_dispatcher/method_behavior`
5657
* (service container) :doc:`/cookbook/service_container/event_listener`

‎cookbook/security/acl.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ several base permissions:
192192
->add('delete')
193193
->add('undelete')
194194
;
195-
$mask = $builder->get(); // int(15)
195+
$mask = $builder->get(); // int(29)
196196
197197
This integer bitmask can then be used to grant a user the base permissions you
198198
added above:

‎reference/constraints/File.rst

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,8 @@ If set, the validator will check that the mime type of the underlying file
171171
is equal to the given mime type (if a string) or exists in the collection
172172
of given mime types (if an array).
173173

174+
You can find a list of existing mime types on the `IANA website`_
175+
174176
maxSizeMessage
175177
~~~~~~~~~~~~~~
176178

@@ -226,4 +228,7 @@ uploadErrorMessage
226228

227229
The message that is displayed if the uploaded file could not be uploaded
228230
for some unknown reason, such as the file upload failed or it couldn't be written
229-
to disk.
231+
to disk.
232+
233+
234+
.. _`IANA website`: http://www.iana.org/assignments/media-types/index.html

0 commit comments

Comments
 (0)
0