Skip to content

Commit 8875c44

Browse files
committed
Merge branch '2.8' into 3.4
* 2.8: Made the testing form examples consistent Updated latest maintained version in documentation overview Remove unused var - custom auth provider example Fixed the params in ChoiceType methods Explain how to check if a route exists Better explain the use of multiple roles in access_control Added notes in the components doc to point to the main Symfony articles Don't recommend base64 encoding of random_bytes result Added a missing validator example Minor tweak about enalbing the profiler in the tests Clarification on search user
2 parents b454cd0 + 35098ee commit 8875c44

29 files changed

+195
-32
lines changed

components/browser_kit.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ Alternatively, you can clone the `<https://github.com/symfony/browser-kit>`_ rep
2828
Basic Usage
2929
-----------
3030

31+
.. seealso::
32+
33+
This article explains how to use the BrowserKit features as an independent
34+
component in any PHP application. Read the :ref:`Symfony Functional Tests <functional-tests>`
35+
article to learn about how to use it in Symfony applications.
36+
3137
Creating a Client
3238
~~~~~~~~~~~~~~~~~
3339

components/console.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ Alternatively, you can clone the `<https://github.com/symfony/console>`_ reposit
2626
Creating a Console Application
2727
------------------------------
2828

29+
.. seealso::
30+
31+
This article explains how to use the Console features as an independent
32+
component in any PHP application. Read the :doc:`/console` article to
33+
learn about how to use it in Symfony applications.
34+
2935
First, you need to create a PHP script to define the console application::
3036

3137
#!/usr/bin/env php

components/css_selector.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,12 @@ Alternatively, you can clone the `<https://github.com/symfony/css-selector>`_ re
2121
Usage
2222
-----
2323

24+
.. seealso::
25+
26+
This article explains how to use the CssSelector features as an independent
27+
component in any PHP application. Read the :ref:`Symfony Functional Tests <functional-tests>`
28+
article to learn about how to use it when creating Symfony tests.
29+
2430
Why to Use CSS selectors?
2531
~~~~~~~~~~~~~~~~~~~~~~~~~
2632

components/dependency_injection.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ Alternatively, you can clone the `<https://github.com/symfony/dependency-injecti
2626
Basic Usage
2727
-----------
2828

29+
.. seealso::
30+
31+
This article explains how to use the DependencyInjection features as an
32+
independent component in any PHP application. Read the :doc:`/service_container`
33+
article to learn about how to use it in Symfony applications.
34+
2935
You might have a simple class like the following ``Mailer`` that
3036
you want to make available as a service::
3137

components/dom_crawler.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ Alternatively, you can clone the `<https://github.com/symfony/dom-crawler>`_ rep
2626
Usage
2727
-----
2828

29+
.. seealso::
30+
31+
This article explains how to use the DomCrawler features as an independent
32+
component in any PHP application. Read the :ref:`Symfony Functional Tests <functional-tests>`
33+
article to learn about how to use it when creating Symfony tests.
34+
2935
The :class:`Symfony\\Component\\DomCrawler\\Crawler` class provides methods
3036
to query and manipulate HTML and XML documents.
3137

components/event_dispatcher.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,12 @@ Alternatively, you can clone the `<https://github.com/symfony/event-dispatcher>`
6363
Usage
6464
-----
6565

66+
.. seealso::
67+
68+
This article explains how to use the EventDispatcher features as an
69+
independent component in any PHP application. Read the :doc:`/event_dispatcher`
70+
article to learn about how to use it in Symfony applications.
71+
6672
Events
6773
~~~~~~
6874

components/form.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,11 @@ Alternatively, you can clone the `<https://github.com/symfony/form>`_ repository
2727
Configuration
2828
-------------
2929

30-
.. tip::
30+
.. seealso::
3131

32-
If you are working with the full-stack Symfony Framework, the Form component
33-
is already configured for you. In this case, skip to :ref:`component-form-intro-create-simple-form`.
32+
This article explains how to use the Form features as an independent
33+
component in any PHP application. Read the :doc:`/forms` article to learn
34+
about how to use it in Symfony applications.
3435

3536
In Symfony, forms are represented by objects and these objects are built
3637
by using a *form factory*. Building a form factory is simple::

components/http_foundation.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,13 @@ Alternatively, you can clone the `<https://github.com/symfony/http-foundation>`_
2727

2828
.. include:: /components/require_autoload.rst.inc
2929

30+
.. seealso::
31+
32+
This article explains how to use the HttpFoundation features as an
33+
independent component in any PHP application. In Symfony applications
34+
everything is already configured and ready to use. Read the :doc:`/controller`
35+
article to learn about how to use these features when creating controllers.
36+
3037
.. _component-http-foundation-request:
3138

3239
Request

components/http_kernel.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ Alternatively, you can clone the `<https://github.com/symfony/http-kernel>`_ rep
2525
The Workflow of a Request
2626
-------------------------
2727

28+
.. seealso::
29+
30+
This article explains how to use the HttpKernel features as an independent
31+
component in any PHP application. In Symfony applications everything is
32+
already configured and ready to use. Read the :doc:`/controller` and
33+
:doc:`/event_dispatcher` articles to learn about how to use it to create
34+
controllers and define events in Symfony applications.
35+
36+
2837
Every HTTP web interaction begins with a request and ends with a response.
2938
Your job as a developer is to create PHP code that reads the request information
3039
(e.g. the URL) and creates and returns a response (e.g. an HTML page or JSON string).

components/intl.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ The Intl Component
1313
The replacement layer is limited to the locale "en". If you want to use
1414
other locales, you should `install the intl extension`_ instead.
1515

16+
.. seealso::
17+
18+
This article explains how to use the Intl features as an independent component
19+
in any PHP application. Read the :doc:`/translation` article to learn about
20+
how to internationalize and manage the user locale in Symfony applications.
21+
1622
Installation
1723
------------
1824

components/phpunit_bridge.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,12 @@ to register a new `test listener`_ called ``SymfonyTestsListener``:
6262
Usage
6363
-----
6464

65+
.. seealso::
66+
67+
This article explains how to use the PhpUnitBridge features as an independent
68+
component in any PHP application. Read the :doc:`/testing` article to learn
69+
about how to use it in Symfony applications.
70+
6571
Once the component is installed, a ``simple-phpunit`` script is created in the
6672
``vendor/`` directory to run tests. This script wraps the original PHPUnit binary
6773
to provide more features:

components/routing.rst

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ Alternatively, you can clone the `<https://github.com/symfony/routing>`_ reposit
2222
Usage
2323
-----
2424

25+
.. seealso::
26+
27+
This article explains how to use the Routing features as an independent
28+
component in any PHP application. Read the :doc:`/routing` article to learn
29+
about how to use it in Symfony applications.
30+
2531
In order to set up a basic routing system you need three parts:
2632

2733
* A :class:`Symfony\\Component\\Routing\\RouteCollection`, which contains the route definitions (instances of the class :class:`Symfony\\Component\\Routing\\Route`)
@@ -229,6 +235,28 @@ a certain route::
229235
of the current :class:`Symfony\\Component\\Routing\\RequestContext` does
230236
not match the requirement.
231237

238+
Check if a Route Exists
239+
~~~~~~~~~~~~~~~~~~~~~~~
240+
241+
In highly dynamic applications, it may be necessary to check whether a route
242+
exists before using it to generate a URL. In those cases, don't use the
243+
:method:`Symfony\\Component\\Routing\\Router::getRouteCollection` method because
244+
that regenerates the routing cache and slows down the application.
245+
246+
Instead, try to generate the URL and catch the
247+
:class:`Symfony\\Component\\Routing\\Exception\\RouteNotFoundException` thrown
248+
when the route doesn't exist::
249+
250+
use Symfony\Component\Routing\Exception\RouteNotFoundException;
251+
252+
// ...
253+
254+
try {
255+
$url = $generator->generate($dynamicRouteName, $parameters);
256+
} catch (RouteNotFoundException $e) {
257+
// the route is not defined...
258+
}
259+
232260
Load Routes from a File
233261
~~~~~~~~~~~~~~~~~~~~~~~
234262

components/security.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ used separately:
3939
``symfony/security-acl``
4040
It provides a fine grained permissions mechanism based on Access Control Lists.
4141

42+
.. seealso::
43+
44+
This article explains how to use the Security features as an independent
45+
component in any PHP application. Read the :doc:`/security` article to learn
46+
about how to use it in Symfony applications.
47+
4248
Learn More
4349
----------
4450

components/security/secure_tools.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,8 @@ the number bytes passed as an argument (10 in the above example).
4141
The ``random_bytes()`` function returns a binary string which may contain
4242
the ``\0`` character. This can cause trouble in several common scenarios,
4343
such as storing this value in a database or including it as part of the
44-
URL. The solution is to encode or hash the value returned by
45-
``random_bytes()`` (to do that, you can use a simple ``base64_encode()``
46-
PHP function).
44+
URL. The solution is to hash the value returned by ``random_bytes()`` with
45+
a hashing function such as :phpfunction:`md5` or :phpfunction:`sha1`.
4746

4847
Generating a Secure Random Number
4948
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

components/serializer.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@ must also be installed.
3838
Usage
3939
-----
4040

41+
.. seealso::
42+
43+
This article explains how to use the Serializer features as an independent
44+
component in any PHP application. Read the :doc:`/serializer` article to
45+
learn about how to use it in Symfony applications.
46+
4147
Using the Serializer component is really simple. You just need to set up
4248
the :class:`Symfony\\Component\\Serializer\\Serializer` specifying
4349
which encoders and normalizer are going to be available::

components/templating.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@ Alternatively, you can clone the `<https://github.com/symfony/templating>`_ repo
2727
Usage
2828
-----
2929

30+
.. seealso::
31+
32+
This article explains how to use the Templating features as an independent
33+
component in any PHP application. Read the :doc:`/templating` article to
34+
learn about how to work with templates in Symfony applications.
35+
3036
The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
3137
of the component. It needs a
3238
template name parser (:class:`Symfony\\Component\\Templating\\TemplateNameParserInterface`)

components/translation.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,13 @@ Alternatively, you can clone the `<https://github.com/symfony/translation>`_ rep
1919

2020
.. include:: /components/require_autoload.rst.inc
2121

22+
.. seealso::
23+
24+
This article explains how to use the Translation features as an independent
25+
component in any PHP application. Read the :doc:`/translation` article to
26+
learn about how to internationalize and manage the user locale in Symfony
27+
applications.
28+
2229
Constructing the Translator
2330
---------------------------
2431

components/validator.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ Alternatively, you can clone the `<https://github.com/symfony/validator>`_ repos
2222
Usage
2323
-----
2424

25+
.. seealso::
26+
27+
This article explains how to use the Validator features as an independent
28+
component in any PHP application. Read the :doc:`/validation` article to
29+
learn about how to validate data and entities in Symfony applications.
30+
2531
The Validator component behavior is based on two concepts:
2632

2733
* Constraints, which define the rules to be validated;

components/validator/metadata.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,3 +70,28 @@ Classes
7070
Some constraints allow to validate the entire object. For example, the
7171
:doc:`Callback </reference/constraints/Callback>` constraint is a generic
7272
constraint that's applied to the class itself.
73+
74+
Suppose that the class defines a ``validate()`` method to hold its custom
75+
validation logic::
76+
77+
// ...
78+
use Symfony\Component\Validator\Context\ExecutionContextInterface;
79+
80+
public function validate(ExecutionContextInterface $context)
81+
{
82+
// ...
83+
}
84+
85+
Then, add the Validator component configuration to the class::
86+
87+
// ...
88+
use Symfony\Component\Validator\Mapping\ClassMetadata;
89+
use Symfony\Component\Validator\Constraints as Assert;
90+
91+
class Author
92+
{
93+
public static function loadValidatorMetadata(ClassMetadata $metadata)
94+
{
95+
$metadata->addConstraint(new Assert\Callback('validate'));
96+
}
97+
}

contributing/documentation/overview.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -112,14 +112,14 @@ memorable name for the new branch (if you are fixing a reported issue, use
112112

113113
.. code-block:: terminal
114114
115-
$ git checkout -b improve_install_article upstream/2.7
115+
$ git checkout -b improve_install_article upstream/2.8
116116
117117
In this example, the name of the branch is ``improve_install_article`` and the
118-
``upstream/2.7`` value tells Git to create this branch based on the ``2.7``
118+
``upstream/2.8`` value tells Git to create this branch based on the ``2.8``
119119
branch of the ``upstream`` remote, which is the original Symfony Docs repository.
120120

121121
Fixes should always be based on the **oldest maintained branch** which contains
122-
the error. Nowadays this is the ``2.7`` branch. If you are instead documenting a
122+
the error. Nowadays this is the ``2.8`` branch. If you are instead documenting a
123123
new feature, switch to the first Symfony version that included it, e.g.
124124
``upstream/3.1``. Not sure? That's ok! Just use the ``upstream/master`` branch.
125125

@@ -155,7 +155,7 @@ changes should be applied:
155155
:align: center
156156

157157
In this example, the **base fork** should be ``symfony/symfony-docs`` and
158-
the **base** branch should be the ``2.7``, which is the branch that you selected
158+
the **base** branch should be the ``2.8``, which is the branch that you selected
159159
to base your changes on. The **head fork** should be your forked copy
160160
of ``symfony-docs`` and the **compare** branch should be ``improve_install_article``,
161161
which is the name of the branch you created and where you made your changes.
@@ -205,7 +205,7 @@ contribution to the Symfony docs:
205205
# create a new branch based on the oldest maintained version
206206
$ cd projects/symfony-docs/
207207
$ git fetch upstream
208-
$ git checkout -b my_changes upstream/2.7
208+
$ git checkout -b my_changes upstream/2.8
209209
210210
# ... do your changes
211211
@@ -288,8 +288,8 @@ into multiple branches, corresponding to the different versions of Symfony itsel
288288
The ``master`` branch holds the documentation for the development branch of
289289
the code.
290290

291-
Unless you're documenting a feature that was introduced after Symfony 2.7,
292-
your changes should always be based on the ``2.7`` branch. Documentation managers
291+
Unless you're documenting a feature that was introduced after Symfony 2.8,
292+
your changes should always be based on the ``2.8`` branch. Documentation managers
293293
will use the necessary Git-magic to also apply your changes to all the active
294294
branches of the documentation.
295295

reference/forms/types/choice.rst

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -94,19 +94,18 @@ method::
9494
new Category('Cat3'),
9595
new Category('Cat4'),
9696
],
97-
'choice_label' => function($category, $key, $index) {
97+
'choice_label' => function($category, $key, $value) {
9898
/** @var Category $category */
9999
return strtoupper($category->getName());
100100
},
101-
'choice_attr' => function($category, $key, $index) {
101+
'choice_attr' => function($category, $key, $value) {
102102
return ['class' => 'category_'.strtolower($category->getName())];
103103
},
104-
105-
'group_by' => function($category, $key, $index) {
104+
'group_by' => function($category, $key, $value) {
106105
// randomly assign things into 2 groups
107106
return rand(0, 1) == 1 ? 'Group A' : 'Group B';
108107
},
109-
'preferred_choices' => function($category, $key, $index) {
108+
'preferred_choices' => function($category, $key, $value) {
110109
return $category->getName() == 'Cat2' || $category->getName() == 'Cat3';
111110
},
112111
]);

reference/forms/types/options/choice_attr.rst.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ If an array, the keys of the ``choices`` array must be used as keys::
1919
'No' => false,
2020
'Maybe' => null,
2121
),
22-
'choice_attr' => function($val, $key, $index) {
22+
'choice_attr' => function($choiceValue, $key, $value) {
2323
// adds a class like attending_yes, attending_no, etc
2424
return ['class' => 'attending_'.strtolower($key)];
2525
},

reference/forms/types/options/choice_label.rst.inc

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,11 @@ more control::
1616
'no' => false,
1717
'maybe' => null,
1818
),
19-
'choice_label' => function ($value, $key, $index) {
20-
if ($value == true) {
19+
'choice_label' => function ($choiceValue, $key, $value) {
20+
if ($value == choiceValue) {
2121
return 'Definitely!';
2222
}
23+
2324
return strtoupper($key);
2425

2526
// or if you want to translate some key

0 commit comments

Comments
 (0)