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

Commit cc5c9a3

Browse files
weaverryanweaverryan
committed
Merge branch '2.4'
Conflicts: reference/dic_tags.rst
2 parents 9d4a138 + 7f7d7a5 commit cc5c9a3

14 files changed

+794
-101
lines changed

‎book/installation.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -247,8 +247,8 @@ If there are any issues, correct them now before moving on.
247247
.. code-block:: bash
248248
249249
$ APACHEUSER=`ps aux | grep -E '[a]pache|[h]ttpd' | grep -v root | head -1 | cut -d\ -f1`
250-
$ sudo setfacl -R -m u:$APACHEUSER:rwX -m u:`whoami`:rwX app/cache app/logs
251-
$ sudo setfacl -dR -m u:$APACHEUSER:rwX -m u:`whoami`:rwX app/cache app/logs
250+
$ sudo setfacl -R -m u:"$APACHEUSER":rwX -m u:`whoami`:rwX app/cache app/logs
251+
$ sudo setfacl -dR -m u:"$APACHEUSER":rwX -m u:`whoami`:rwX app/cache app/logs
252252

253253
**3. Without using ACL**
254254

‎book/validation.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,8 +113,9 @@ Next, to actually validate an ``Author`` object, use the ``validate`` method
113113
on the ``validator`` service (class :class:`Symfony\\Component\\Validator\\Validator`).
114114
The job of the ``validator`` is easy: to read the constraints (i.e. rules)
115115
of a class and verify whether or not the data on the object satisfies those
116-
constraints. If validation fails, an array of errors is returned. Take this
117-
simple example from inside a controller::
116+
constraints. If validation fails, a non-empty list of errors
117+
(class :class:`Symfony\\Component\\Validator\\ConstraintViolationList`) is
118+
returned. Take this simple example from inside a controller:
118119

119120
// ...
120121
use Symfony\Component\HttpFoundation\Response;

‎components/dom_crawler.rst

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,65 @@ To remove a node the anonymous function must return false.
9595
All filter methods return a new :class:`Symfony\\Component\\DomCrawler\\Crawler`
9696
instance with filtered content.
9797 B422

98+
Both the :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath` and
99+
:method:`Symfony\\Component\\DomCrawler\\Crawler::filter` methods work with
100+
XML namespaces, which can be either automatically discovered or registered
101+
explicitly.
102+
103+
.. versionadded:: 2.4
104+
Auto discovery and explicit registration of namespaces was introduced
105+
in Symfony 2.4.
106+
107+
Consider the XML below:
108+
109+
<?xml version="1.0" encoding="UTF-8"?>
110+
<entry
111+
xmlns="http://www.w3.org/2005/Atom"
112+
xmlns:media="http://search.yahoo.com/mrss/"
113+
xmlns:yt="http://gdata.youtube.com/schemas/2007">
114+
<id>tag:youtube.com,2008:video:kgZRZmEc9j4</id>
115+
<yt:accessControl action="comment" permission="allowed"/>
116+
<yt:accessControl action="videoRespond" permission="moderated"/>
117+
<media:group>
118+
<media:title type="plain">Chordates - CrashCourse Biology #24</media:title>
119+
<yt:aspectRatio>widescreen</yt:aspectRatio>
120+
</media:group>
121+
</entry>
122+
123+
This can be filtered with the ``Crawler`` without needing to register namespace
124+
aliases both with :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath`::
125+
126+
$crawler = $crawler->filterXPath('//default:entry/media:group//yt:aspectRatio');
127+
128+
and :method:`Symfony\\Component\\DomCrawler\\Crawler::filter`::
129+
130+
use Symfony\Component\CssSelector\CssSelector;
131+
132+
CssSelector::disableHtmlExtension();
133+
$crawler = $crawler->filter('default|entry media|group yt|aspectRatio');
134+
135+
.. note::
136+
137+
The default namespace is registered with a prefix "default". It can be
138+
changed with the
139+
:method:`Symfony\\Component\\DomCrawler\\Crawler::setDefaultNamespacePrefix`
140+
method.
141+
142+
The default namespace is removed when loading the content if it's the only
143+
namespace in the document. It's done to simplify the xpath queries.
144+
145+
Namespaces can be explicitly registered with the
146+
:method:`Symfony\\Component\\DomCrawler\\Crawler::registerNamespace` method::
147+
148+
$crawler->registerNamespace('m', 'http://search.yahoo.com/mrss/');
149+
$crawler = $crawler->filterXPath('//m:group//yt:aspectRatio');
150+
151+
.. caution::
152+
153+
To query XML with a CSS selector, the HTML extension needs to be disabled with
154+
:method:`CssSelector::disableHtmlExtension <Symfony\\Component\\CssSelector\\CssSelector::disableHtmlExtension>`
155+
to avoid converting the selector to lowercase.
156+
98157
Node Traversing
99158
~~~~~~~~~~~~~~~
100159

‎components/form/introduction.rst

Lines changed: 43 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -66,15 +66,23 @@ factory.
6666
Request Handling
6767
~~~~~~~~~~~~~~~~
6868

69-
To process form data, you'll need to grab information off of the request (typically
70-
``$_POST`` data) and pass the array of submitted data to
71-
:method:`Symfony\\Component\\Form\\Form::bind`. The Form component optionally
72-
integrates with Symfony's :doc:`HttpFoundation </components/http_foundation/introduction>`
73-
component to make this even easier.
69+
.. versionadded:: 2.3
70+
The ``handleRequest()`` method was added in Symfony 2.3.
7471

75-
To integrate the HttpFoundation component, add the
76-
:class:`Symfony\\Component\\Form\\Extension\\HttpFoundation\\HttpFoundationExtension`
77-
to your form factory::
72+
To process form data, you'll need to call the :method:`Symfony\\Component\\Form\\Form::handleRequest`
73+
method::
74+
75+
$form->handleRequest();
76+
77+
Behind the scenes, this uses a :class:`Symfony\\Component\\Form\\NativeRequestHandler`
78+
object to read data off of the correct PHP superglobals (i.e. ``$_POST`` or
79+
``$_GET``) based on the HTTP method configured on the form (POST is default).
80+
81+
.. sidebar:: Integration with the HttpFoundation Component
82+
83+
If you use the HttpFoundation component, then you should add the
84+
:class:`Symfony\\Component\\Form\\Extension\\HttpFoundation\\HttpFoundationExtension`
85+
to your form factory::
7886

7987
use Symfony\Component\Form\Forms;
8088
use Symfony\Component\Form\Extension\HttpFoundation\Ht E377 tpFoundationExtension;
@@ -83,14 +91,15 @@ to your form factory::
8391
->addExtension(new HttpFoundationExtension())
8492
->getFormFactory();
8593

86-
Now, when you process a form, you can pass the :class:`Symfony\\Component\\HttpFoundation\\Request`
87-
object to :method:`Symfony\\Component\\Form\\Form::bind` instead of the raw
88-
array of submitted values.
94+
Now, when you process a form, you can pass the :class:`Symfony\\Component\\HttpFoundation\\Request`
95+
object to :method:`Symfony\\Component\\Form\\Form::handleRequest`::
8996

90-
.. note::
97+
$form->handleRequest($request);
9198

92-
For more information about the HttpFoundation component or how to
93-
install it, see :doc:`/components/http_foundation/introduction`.
99+
.. note::
100+
101+
For more information about the HttpFoundation component or how to
102+
install it, see :doc:`/components/http_foundation/introduction`.
94103

95104
CSRF Protection
96105
~~~~~~~~~~~~~~~
@@ -480,7 +489,7 @@ to do that in the ":ref:`form-rendering-template`" section.
480489
Handling Form Submissions
481490
~~~~~~~~~~~~~~~~~~~~~~~~~
482491

483-
To handle form submissions, use the :method:`Symfony\\Component\\Form\\Form::bind`
492+
To handle form submissions, use the :method:`Symfony\\Component\\Form\\Form::handleRequest`
484493
method:
485494

486495
.. configuration-block::
@@ -497,19 +506,17 @@ method:
497506
498507
$request = Request::createFromGlobals();
499508
500-
if ($request->isMethod('POST')) {
501-
$form->bind($request);
509+
$form->handleRequest($request);
502510
503-
if ($form->isValid()) {
504-
$data = $form->getData();
511+
if ($form->isValid()) {
512+
$data = $form->getData();
505513
506-
// ... perform some action, such as saving the data to the database
514+
// ... perform some action, such as saving the data to the database
507515
508-
$response = new RedirectResponse('/task/success');
509-
$response->prepare($request);
516+
$response = new RedirectResponse('/task/success');
517+
$response->prepare($request);
510518
511-
return $response->send();
512-
}
519+
return $response->send();
513520
}
514521
515522
// ...
@@ -525,17 +532,14 @@ method:
525532
->add('dueDate', 'date')
526533
->getForm();
527534
528-
// only process the form if the request is a POST request
529-
if ($request->isMethod('POST')) {
530-
$form->bind($request);
535+
$form->handleRequest($request);
531536
532-
if ($form->isValid()) {
533-
$data = $form->getData();
537+
if ($form->isValid()) {
538+
$data = $form->getData();
534539
535-
// ... perform some action, such as saving the data to the database
540+
// ... perform some action, such as saving the data to the database
536541
537- return $this->redirect($this->generateUrl('task_success'));
538-
}
542+
return $this->redirect($this->generateUrl('task_success'));
539543
}
540544
541545
// ...
@@ -546,25 +550,15 @@ This defines a common form "workflow", which contains 3 different possibilities:
546550
1) On the initial GET request (i.e. when the user "surfs" to your page),
547551
build your form and render it;
548552

549-
If the request is a POST, process the submitted data (via ``bind``). Then:
550-
551-
2) if the form is invalid, re-render the form (which will now contain errors)
552-
3) if the form is valid, perform some action and redirect;
553-
554-
.. note::
555-
556-
If you're not using HttpFoundation, just pass the POST'ed data directly
557-
to ``bind``::
558-
559-
if (isset($_POST[$form->getName()])) {
560-
$form->bind($_POST[$form->getName()]);
553+
If the request is a POST, process the submitted data (via ``handleRequest()``).
554+
Then:
561555

562-
// ...
563-
}
556+
2) if the form is invalid, re-render the form (which will now contain errors);
557+
3) if the form is valid, perform some action and redirect.
564558

565-
If you're uploading files, you'll need to do a little bit more work by
566-
merging the ``$_POST`` array with the ``$_FILES`` array before passing
567-
it into ``bind``.
559+
Luckily, you don't need to decide whether or not a form has been submitted.
560+
Just pass the current request to the ``handleRequest()`` method. Then, the Form
561+
component will do all the necessary work for you.
568562

569563
.. _component-form-intro-validation:
570564

‎contributing/documentation/overview.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -29,17 +29,17 @@ Consistent with Symfony's source code, the documentation repository is split int
2929
multiple branches, corresponding to the different versions of Symfony itself.
3030
The ``master`` branch holds the documentation for the development branch of the code.
3131

32-
Unless you're documenting a feature that was introduced *after* Symfony 2.2
33-
(e.g. in Symfony 2.3), your changes should always be based on the 2.2 branch.
34-
To do this checkout the 2.2 branch before the next step:
32+
Unless you're documenting a feature that was introduced *after* Symfony 2.3
33+
(e.g. in Symfony 2.4), your changes should always be based on the 2.3 branch.
34+
To do this checkout the 2.3 branch before the next step:
3535

3636
.. code-block:: bash
3737
38-
$ git checkout 2.2
38+
$ git checkout 2.3
3939
4040
.. tip::
4141

42-
Your base branch (e.g. 2.2) will become the "Applies to" in the :ref:`doc-contributing-pr-format`
42+
Your base branch (e.g. 2.3) will become the "Applies to" in the :ref:`doc-contributing-pr-format`
4343
that you'll use later.
4444

4545
Next, create a dedicated branch for your changes (for organization):
@@ -57,17 +57,17 @@ Creating a Pull Request
5757
Following the example, the pull request will default to be between your
5858
``improving_foo_and_bar`` branch and the ``symfony-docs`` ``master`` branch.
5959

60-
If you have made your changes based on the 2.2 branch then you need to change
61-
the base branch to be 2.2 on the preview page by clicking the ``edit`` button
60+
If you have made your changes based on the 2.3 branch then you need to change
61+
the base branch to be 2.3 on the preview page by clicking the ``edit`` button
6262
on the top left:
6363

6464
.. image:: /images/docs-pull-request-change-base.png
6565
:align: center
6666

6767
.. note::
6868

69-
All changes made to a branch (e.g. 2.2) will be merged up to each "newer"
70-
branch (e.g. 2.3, master, etc) for the next release on a weekly basis.
69+
All changes made to a branch (e.g. 2.3) will be merged up to each "newer"
70+
branch (e.g. 2.4, master, etc) for the next release on a weekly basis.
7171

7272
GitHub covers the topic of `pull requests`_ in detail.
7373

‎contributing/documentation/standards.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,14 @@ Language Standards
125125
* Do not use `Serial (Oxford) Commas`_;
126126
* You should use a form of *you* instead of *we* (i.e. avoid the first person
127127
point of view: use the second instead).
128+
* When referencing a hypothetical person, such as "a user with a session cookie", gender-neutral
129+
pronouns (they/their/them) should be used. For example, instead of:
130+
131+
* he or she, use they
132+
* him or her, use them
133+
* his or her, use their
134+
* his or hers, use theirs
135+
* himself or herself, use themselves
128136

129137
.. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
130138
.. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html

‎cookbook/form/direct_submit.rst

Lines changed: 8 additions & 8 deletions
F3BF
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ submissions::
2727

2828
return $this->redirect($this->generateUrl('task_success'));
2929
}
30-
30+
3131
return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
3232
'form' => $form->createView(),
3333
));
@@ -45,9 +45,9 @@ Calling Form::submit() manually
4545

4646
In some cases, you want better control over when exactly your form is submitted
4747
and what data is passed to it. Instead of using the
48-
:method:`Symfony\Component\Form\FormInterface::handleRequest`
48+
:method:`Symfony\\Component\\Form\\FormInterface::handleRequest`
4949
method, pass the submitted data directly to
50-
:method:`Symfony\Component\Form\FormInterface::submit`::
50+
:method:`Symfony\\Component\\Form\\FormInterface::submit`::
5151

5252
use Symfony\Component\HttpFoundation\Request;
5353
// ...
@@ -76,8 +76,8 @@ method, pass the submitted data directly to
7676
.. tip::
7777

7878
Forms consisting of nested fields expect an array in
79-
:method:`Symfony\Component\Form\FormInterface::submit`. You can also submit
80-
individual fields by calling :method:`Symfony\Component\Form\FormInterface::submit`
79+
:method:`Symfony\\Component\\Form\\FormInterface::submit`. You can also submit
80+
individual fields by calling :method:`Symfony\\Component\\Form\\FormInterface::submit`
8181
directly on the field::
8282

8383
$form->get('firstName')->submit('Fabien');
@@ -90,7 +90,7 @@ Passing a Request to Form::submit() (deprecated)
9090
.. versionadded:: 2.3
9191
Before Symfony 2.3, the ``submit`` method was known as ``bind``.
9292

93-
Before Symfony 2.3, the :method:`Symfony\Component\Form\FormInterface::submit`
93+
Before Symfony 2.3, the :method:`Symfony\\Component\\Form\\FormInterface::submit`
9494
method accepted a :class:`Symfony\\Component\\HttpFoundation\\Request` object as
9595
a convenient shortcut to the previous example::
9696

@@ -118,7 +118,7 @@ a convenient shortcut to the previous example::
118118
));
119119
}
120120

121-
Passing the :class:`Symfony\\Component\HttpFoundation\\Request` directly to
121+
Passing the :class:`Symfony\\Component\\HttpFoundation\\Request` directly to
122122
:method:`Symfony\\Component\\Form\\FormInterface::submit` still works, but is
123123
deprecated and will be removed in Symfony 3.0. You should use the method
124-
:method:`Symfony\Component\Form\FormInterface::handleRequest` instead.
124+
:method:`Symfony\\Component\\Form\\FormInterface::handleRequest` instead.

‎cookbook/map.rst.inc

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,12 @@
132132
* :doc:`/cookbook/security/acl`
133133
* :doc:`/cookbook/security/acl_advanced`
134134
* :doc:`/cookbook/security/force_https`
135+
* :doc:`/cookbook/security/host_restriction`
135136
* :doc:`/cookbook/security/form_login`
136137
* :doc:`/cookbook/security/securing_services`
137138
* :doc:`/cookbook/security/custom_provider`
139+
* :doc:`/cookbook/security/custom_password_authenticator`
140+
* :doc:`/cookbook/security/api_key_authentication`
138141
* :doc:`/cookbook/security/custom_authentication_provider`
139142
* :doc:`/cookbook/security/target_path`
140143

0 commit comments

Comments
 (0)
0