8000 Merge branch '4.0' · symfony/symfony-docs@903f302 · GitHub
[go: up one dir, main page]
Skip to content

Commit 903f302

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.0'
* 4.0: Updated HttpKernel component diagrams fix code block syntax Change value for opcache.memory_consumption Added a note about the dangers of dumping $_SERVER and $_ENV Updated the Guard diagram to add the new supports() method Fixed a missing reference Improved a routing example to show annotations Documented how to parse and dump custom YAML tags Clearer wording of allow_delete template behavior
2 parents 713718f + 5442d7a commit 903f302

27 files changed

+95
-52
lines changed

‎_images/components/http_kernel/01-workflow.png

-123 KB
Binary file not shown.

‎_images/components/http_kernel/02-kernel-request.png

-119 KB
Binary file not shown.

‎_images/components/http_kernel/03-kernel-request-response.png

-119 KB
Binary file not shown.

‎_images/components/http_kernel/04-resolve-controller.png

-118 KB
Binary file not shown.

‎_images/components/http_kernel/06-kernel-controller.png

-121 KB
Binary file not shown.

‎_images/components/http_kernel/07-controller-arguments.png

-122 KB
Binary file not shown.

‎_images/components/http_kernel/08-call-controller.png

-122 KB
Binary file not shown.

‎_images/components/http_kernel/09-controller-returns-response.png

-123 KB
Binary file not shown.

‎_images/components/http_kernel/10-kernel-view.png

-121 KB
Binary file not shown.

‎_images/components/http_kernel/11-kernel-exception.png

-123 KB
Binary file not shown.

‎_images/components/http_kernel/http-workflow-exception.svg

Lines changed: 1 addition & 0 deletions
Loading

‎_images/components/http_kernel/http-workflow-subrequest.svg

Lines changed: 1 addition & 0 deletions
Loading

‎_images/components/http_kernel/http-workflow.svg

Lines changed: 1 addition & 0 deletions
Loading

‎_images/components/http_kernel/request-response-flow.png

-327 KB
Binary file not shown.

‎_images/components/http_kernel/sub-request.png

-125 KB
Binary file not shown.

‎_images/security/authentication-guard-methods.svg

Lines changed: 1 addition & 1 deletion
Loading

‎_images/sources/http_kernel/http-workflow.dia

3.7 KB
Binary file not shown.

‎_images/sources/security/authentication-guard-methods.dia

284 Bytes
Binary file not shown.

‎best_practices/configuration.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,13 @@ they have nothing to do with the application's behavior. In other words, your
4242
application doesn't care about the location of your database or the credentials
4343
to access to it, as long as the database is correctly configured.
4444

45+
.. caution::
46+
47+
Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
48+
or outputting the ``phpinfo()`` contents will display the values of the
49+
environment variables, exposing sensitive information such as the database
50+
credentials.
51+
4552
.. _best-practices-canonical-parameters:
4653

4754
Canonical Parameters

‎components/http_kernel.rst

Lines changed: 16 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,14 @@ The Workflow of a Request
2727
Every HTTP web interaction begins with a request and ends with a response.
2828
Your job as a developer is to create PHP code that reads the request information
2929
(e.g. the URL) and creates and returns a response (e.g. an HTML page or JSON string).
30+
This is a simplified overview of the request workflow in Symfony applications:
3031

31-
.. image:: /_images/components/http_kernel/request-response-flow.png
32-
:align: center
32+
#. The **user** asks for a **resource** in a **browser**;
33+
#. The **browser** sends a **request** to the **server**;
34+
#. **Symfony** gives the **application** a **Request** object;
35+
#. The **application** generates a **Response** object using the data of the **Request** object;
36+
#. The **server** sends back the **response** to the **browser**;
37+
#. The **browser** displays the **resource** to the **user**.
3338

3439
Typically, some sort of framework or system is built to handle all the repetitive
3540
tasks (e.g. routing, security, etc) so that a developer can easily build
@@ -62,8 +67,9 @@ the concrete implementation of :method:`HttpKernelInterface::handle() <Symfony\\
6267
defines a workflow that starts with a :class:`Symfony\\Component\\HttpFoundation\\Request`
6368
and ends with a :class:`Symfony\\Component\\HttpFoundation\\Response`.
6469

65-
.. image:: /_images/components/http_kernel/01-workflow.png
66-
:align: center
70+
.. raw:: html
71+
72+
<object data="../_images/components/http_kernel/http-workflow.svg" type="image/svg+xml"></object>
6773

6874
The exact details of this workflow are the key to understanding how the kernel
6975
(and the Symfony Framework or any other library that uses the kernel) works.
@@ -149,9 +155,6 @@ layer that denies access).
149155
The first event that is dispatched inside :method:`HttpKernel::handle <Symfony\\Component\\HttpKernel\\HttpKernel::handle>`
150156
is ``kernel.request``, which may have a variety of different listeners.
151157

152-
.. image:: /_images/components/http_kernel/02-kernel-request.png
153-
:align: center
154-
155158
Listeners of this event can be quite varied. Some listeners - such as a security
156159
listener - might have enough information to create a ``Response`` object immediately.
157160
For example, if a security listener determined that a user doesn't have access,
@@ -161,9 +164,6 @@ to the login page or a 403 Access Denied response.
161164
If a ``Response`` is returned at this stage, the process skips directly to
162165
the :ref:`kernel.response <component-http-kernel-kernel-response>` event.
163166

164-
.. image:: /_images/components/http_kernel/03-kernel-request-response.png
165-
:align: center
166-
167167
Other listeners simply initialize things or add more information to the request.
168168
For example, a listener might determine and set the locale on the ``Request``
169169
object.
@@ -216,9 +216,6 @@ to your application. This is the job of the "controller resolver" - a class
216216
that implements :class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface`
217217
and is one of the constructor arguments to ``HttpKernel``.
218218

219-
.. image:: /_images/components/http_kernel/04-resolve-controller.png
220-
:align: center
221-
222219
Your job is to create a class that implements the interface and fill in its
223220
method: ``getController()``. In fact, one default implementation already
224221
exists, which you can use directly or learn from:
@@ -286,9 +283,6 @@ some part of the system that needs to be initialized after certain things
286283
have been determined (e.g. the controller, routing information) but before
287284
the controller is executed. For some examples, see the Symfony section below.
288285

289-
.. image:: /_images/components/http_kernel/06-kernel-controller.png
290-
:align: center
291-
292286
Listeners to this event can also change the controller callable completely
293287
by calling :method:`FilterControllerEvent::setController <Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent::setController>`
294288
on the event object that's passed to listeners on this event.
@@ -319,9 +313,6 @@ should be passed to that controller. Exactly how this is done is completely
319313
up to your design, though the built-in :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver`
320314
is a good example.
321315

322-
.. image:: /_images/components/http_kernel/07-controller-arguments.png
323-
:align: center
324-
325316
At this point the kernel has a PHP callable (the controller) and an array
326317
of arguments that should be passed when executing that callable.
327318

@@ -362,9 +353,6 @@ of arguments that should be passed when executing that callable.
362353

363354
The next step is simple! ``HttpKernel::handle()`` executes the controller.
364355

365-
.. image:: /_images/components/http_kernel/08-call-controller.png
366-
:align: center
367-
368356
The job of the controller is to build the response for the given resource.
369357
This could be an HTML page, a JSON string or anything else. Unlike every
370358
other part of the process so far, this step is implemented by the "end-developer",
@@ -374,9 +362,6 @@ Usually, the controller will return a ``Response`` object. If this is true,
374362
then the work of the kernel is just about done! In this case, the next step
375363
is the :ref:`kernel.response <component-http-kernel-kernel-response>` event.
376364

377-
.. image:: /_images/components/http_kernel/09-controller-returns-response.png
378-
:align: center
379-
380365
But if the controller returns anything besides a ``Response``, then the kernel
381366
has a little bit more work to do - :ref:`kernel.view <component-http-kernel-kernel-view>`
382367
(since the end goal is *always* to generate a ``Response`` object).
@@ -401,9 +386,6 @@ another event - ``kernel.view``. The job of a listener to this event is to
401386
use the return value of the controller (e.g. an array of data or an object)
402387
to create a ``Response``.
403388

404-
.. image:: /_images/components/http_kernel/10-kernel-view.png
405-
:align: center
406-
407389
This can be useful if you want to use a "view" layer: instead of returning
408390
a ``Response`` from the controller, you return data that represents the page.
409391
A listener to this event could then use this data to create a ``Response`` that
@@ -531,8 +513,9 @@ function is wrapped in a try-catch block. When any exception is thrown, the
531513
``kernel.exception`` event is dispatched so that your system can somehow respond
532514
to the exception.
533515

534-
.. image:: /_images/components/http_kernel/11-kernel-exception.png
535-
:align: center
516+
.. raw:: html
517+
518+
<object data="../_images/components/http_kernel/http-workflow-exception.svg" type="image/svg+xml"></object>
536519

537520
Each listener to this event is passed a :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`
538521
object, which you can use to access the original exception via the
@@ -688,8 +671,9 @@ a page instead of a full page. You'll most commonly make sub-requests from
688671
your controller (or perhaps from inside a template, that's being rendered by
689672
your controller).
690673

691-
.. image:: /_images/components/http_kernel/sub-request.png
692-
:align: center
674+
.. raw:: html
675+
676+
<object data="../_images/components/http_kernel/http-workflow-subrequest.svg" type="image/svg+xml"></object>
693677

694678
To execute a sub request, use ``HttpKernel::handle()``, but change the second
695679
argument as follows::

‎components/yaml.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -364,6 +364,31 @@ Binary data is automatically parsed if they include the ``!!binary`` YAML tag
364364
$parsed = Yaml::parse($dumped);
365365
$imageContents = $parsed['logo'];
366366

367+
Parsing and Dumping Custom Tags
368+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
369+
370+
.. versionadded:: 3.3
371+
Support for parsing and dumping custom tags was introduced in Symfony 3.3.
372+
373+
In addition to the built-in support of tags like ``!php/const`` and
374+
``!!binary``, you can define your own custom YAML tags and parse them with the
375+
``PARSE_CUSTOM_TAGS`` flag::
376+
377+
$data = "!my_tag { foo: bar }";
378+
$parsed = Yaml::parse($data, Yaml::PARSE_CUSTOM_TAGS);
379+
// $parsed = Symfony\Component\Yaml\Tag\TaggedValue('my_tag', array('foo' => 'bar'));
380+
$tagName = $parsed->getTag(); // $tagName = 'my_tag'
381+
$tagValue = $parsed->getValue(); // $tagValue = array('foo' => 'bar')
382+
383+
If the contents to dump contain :class:`Symfony\\Component\\Yaml\\Tag\\TaggedValue`
384+
objects, they are automatically transformed into YAML tags::
385+
386+
use Symfony\Component\Yaml\Tag\TaggedValue;
387+
388+
$data = new TaggedValue('my_tag', array('foo' => 'bar'));
389+
$dumped = Yaml::dump($data);
390+
// $dumped = '!my_tag { foo: bar }'
391+
367392
Syntax Validation
368393
~~~~~~~~~~~~~~~~~
369394

‎configuration/external_parameters.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,13 @@ the following:
123123
124124
fastcgi_param DATABASE_URL "mysql://db_user:db_password@127.0.0.1:3306/db_name";
125125
126+
.. caution::
127+
128+
Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
129+
or outputting the ``phpinfo()`` contents will display the values of the
130+
environment variables, exposing sensitive information such as the database
131+
credentials.
132+
126133
Constants
127134
---------
128135

‎form/form_collections.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -616,9 +616,11 @@ No 325D w, you need to put some code into the ``removeTag()`` method of ``Task``::
616616
Template Modifications
617617
~~~~~~~~~~~~~~~~~~~~~~
618618

619-
The ``allow_delete`` option has one consequence: if an item of a collection
619+
The ``allow_delete`` option means that if an item of a collection
620620
isn't sent on submission, the related data is removed from the collection
621-
on the server. The solution is to remove the form element from the DOM.
621+
on the server. In order for this to work in an HTML form, you must remove
622+
the DOM element for the collection item to be removed, before submitting
623+
the form.
622624

623625
First, add a "delete this tag" link to each tag form:
624626

‎performance.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ it's recommended to change these settings as follows:
5454
5555
; php.ini
5656
; maximum memory that OPcache can use to store compiled PHP files
57-
opcache.memory_consumption=256M
57+
opcache.memory_consumption=256
5858
5959
; maximum number of files that can be stored in the cache
6060
opcache.max_accelerated_files=20000

‎routing/external_resources.rst

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,15 +85,29 @@ This can be done by importing routing resources from the main routing file:
8585
When importing resources from YAML, the key (e.g. ``app_file``) is meaningless.
8686
Just be sure that it's unique so no other lines override it.
8787

88-
Prefixing Imported Routes
89-
~~~~~~~~~~~~~~~~~~~~~~~~~
88+
.. _prefixing-imported-routes:
89+
90+
Prefixing the URLs of Imported Routes
91+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9092

9193
You can also choose to provide a "prefix" for the imported routes. For example,
9294
suppose you want to prefix all application routes with ``/site`` (e.g.
9395
``/site/blog/{slug}`` instead of ``/blog/{slug}``):
9496

9597
.. configuration-block::
9698

99+
.. code-block:: php-annotations
100+
101+
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
102+
103+
/**
104+
* @Route("/site")
105+
*/
106+
class DefaultController
107+
{
108+
// ...
109+
}
110+
97111
.. code-block:: yaml
98112
99113
# config/routes.yaml

‎security/form_login_setup.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -161,8 +161,9 @@ Great! Next, add the logic to ``login()`` that displays the login form::
161161
.. note::
162162

163163
If you get an error that the ``$authUtils`` argument is missing, it's
164-
probably because you need to activate this new feature in Symfony 3.4. See
165-
this :ref:`controller service argument note <controller-service-arguments-tag>`.
164+
probably because the controllers of your application are not defined as
165+
services and tagged with the ``controller.service_arguments`` tag, as done
166+
in the :ref:`default services.yaml configuration <service-container-services-load-example>`.
166167

167168
Don't let this controller confuse you. As you'll see in a moment, when the
168169
user submits the form, the security system automatically handles the form

‎service_container.rst

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -920,19 +920,19 @@ for classes under the same namespace:
920920
In order to have multiple definitions, add the ``namespace`` option and use any
921921
unique string as the key of each service config:
922922

923-
.. code-block:: yaml
923+
.. code-block:: yaml
924924
925-
# app/config/services.yml
926-
services:
927-
command_handlers:
928-
namespace: App\Domain\
929-
resource: '../../src/Domain/*/CommandHandler'
930-
tags: [command_handler]
931-
932-
event_subscribers:
933-
namespace: App\Domain\
934-
resource: '../../src/Domain/*/EventSubscriber'
935-
tags: [event_subscriber]
925+
# app/config/services.yml
926+
services:
927+
command_handlers:
928+
namespace: App\Domain\
929+
resource: '../../src/Domain/*/CommandHandler'
930+
tags: [command_handler]
931+
932+
event_subscribers:
933+
namespace: App\Domain\
934+
resource: '../../src/Domain/*/EventSubscriber'
935+
tags: [event_subscriber]
936936
937937
.. _services-explicitly-configure-wire-services:
938938

0 commit comments

Comments
 (0)
0