Skip to content

Commit a41964e

Browse files
committed
Merge branch '2.7' into 2.8
* 2.7: (31 commits) Fixed the RST syntax Improve example context [#5621] Enhancing example of using bundle config [#7601] minor tweak Update expiration.rst Update expiration.rst Update expiration.rst Update expiration.rst Minor reword and fixed the line length Improve specification explanation [#7664] minor wording tweak Rewords and minor fixes Add an explanation about «constraints» validation [#7645] enumerate ordered list items implicitly Adding a new article about "Creating a Bug Reproducer" Fixed a syntax issue Use backticks #7311 choice_value callback argument can be null Fixed broken links for nginx & FastCgiExternalServer Update dialoghelper.rst ...
2 parents c2727e5 + 769e893 commit a41964e

File tree

15 files changed

+343
-100
lines changed

15 files changed

+343
-100
lines changed

bundles/configuration.rst

Lines changed: 48 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -218,18 +218,64 @@ This class can now be used in your ``load()`` method to merge configurations and
218218
force validation (e.g. if an additional option was passed, an exception will be
219219
thrown)::
220220

221+
// src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
222+
221223
public function load(array $configs, ContainerBuilder $container)
222224
{
223225
$configuration = new Configuration();
224226

225227
$config = $this->processConfiguration($configuration, $configs);
226-
// ...
228+
229+
// you now have these 2 config keys
230+
// $config['twitter']['client_id'] and $config['twitter']['client_secret']
227231
}
228232

229233
The ``processConfiguration()`` method uses the configuration tree you've defined
230234
in the ``Configuration`` class to validate, normalize and merge all the
231235
configuration arrays together.
232236

237+
Now, you can use the ``$config`` variable to modify a service provided by your bundle.
238+
For example, imagine your bundle has the following example config:
239+
240+
.. code-block:: xml
241+
242+
<!-- src/Acme/SocialBundle/Resources/config/services.xml -->
243+
<?xml version="1.0" encoding="UTF-8" ?>
244+
<container xmlns="http://symfony.com/schema/dic/services"
245+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
246+
xsi:schemaLocation="http://symfony.com/schema/dic/services
247+
http://symfony.com/schema/dic/services/services-1.0.xsd">
248+
249+
<services>
250+
<service id="acme.social.twitter_client" class="Acme\SocialBundle\TwitterClient">
251+
<argument></argument> <!-- will be filled in with client_id dynamically -->
252+
<argument></argument> <!-- will be filled in with client_secret dynamically -->
253+
</service>
254+
</services>
255+
</container>
256+
257+
In your extension, you can load this and dynamically set its arguments::
258+
259+
// src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
260+
// ...
261+
262+
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
263+
use Symfony\Component\Config\FileLocator;
264+
265+
public function load(array $configs, ContainerBuilder $container)
266+
{
267+
$loader = new XmlFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
268+
$loader->load('services.xml');
269+
270+
$configuration = new Configuration();
271+
$config = $this->processConfiguration($configuration, $configs);
272+
273+
$def = $container->getDefinition('acme.social.twitter_client');
274+
$def->replaceArgument(0, $config['twitter']['client_id']);
275+
$def->replaceArgument(1, $config['twitter']['client_secret']);
276+
}
277+
278+
233279
.. tip::
234280

235281
Instead of calling ``processConfiguration()`` in your extension each time you
@@ -253,9 +299,7 @@ configuration arrays together.
253299
}
254300

255301
This class uses the ``getConfiguration()`` method to get the Configuration
256-
instance. You should override it if your Configuration class is not called
257-
``Configuration`` or if it is not placed in the same namespace as the
258-
extension.
302+
instance.
259303

260304
.. sidebar:: Processing the Configuration yourself
261305

components/console/helpers/dialoghelper.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ method::
125125
'AcmeDemoBundle'
126126
);
127127

128-
This methods has 2 new arguments, the full signature is::
128+
This method has 2 new arguments, the full signature is::
129129

130130
askAndValidate(
131131
OutputInterface $output,

console/coloring.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,12 @@ You can also set these colors and options directly inside the tagname::
6565
// bold text on a yellow background
6666
$output->writeln('<bg=yellow;options=bold>foo</>');
6767

68+
.. note::
69+
70+
If you need to render a tag literally, escape it with a backslash: ``\<info>``
71+
or use the :method:`Symfony\\Component\\Console\\Formatter\\OutputFormatter::escape`
72+
method to escape all the tags included in the given string.
73+
6874
.. _Cmder: http://cmder.net/
6975
.. _ConEmu: https://conemu.github.io/
7076
.. _ANSICON: https://github.com/adoxa/ansicon/releases

contributing/code/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Contributing Code
55
:maxdepth: 2
66

77
bugs
8+
reproducer
89
patches
910
maintenance
1011
core_team

contributing/code/reproducer.rst

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
Creating a Bug Reproducer
2+
=========================
3+
4+
The main Symfony code repository receives thousands of issues reports per year.
5+
Some of those issues are so obvious or easy to understand, that Symfony Core
6+
developers can fix them without any other information. However, other issues are
7+
much harder to understand because developers can't easily reproduce them in their
8+
computers. That's when we'll ask you to create a "bug reproducer", which is the
9+
minimum amount of code needed to make the bug appear when executed.
10+
11+
Reproducing Simple Bugs
12+
-----------------------
13+
14+
If you are reporting a bug related to some Symfony component used outside the
15+
Symfony framework, it's enough to share a small PHP script that when executed
16+
shows the bug::
17+
18+
// First, run "composer require symfony/validator"
19+
// Then, execute this file:
20+
<?php
21+
require_once __DIR__.'/vendor/autoload.php';
22+
use Symfony\Component\Validator\Constraints;
23+
24+
$wrongUrl = 'http://example.com/exploit.html?<script>alert(1);</script>';
25+
$urlValidator = new Constraints\UrlValidator();
26+
$urlConstraint = new Constraints\Url();
27+
28+
// The URL is wrong, so var_dump() should display an error, but it displays
29+
// "null" instead because there is no context to build a validator violation
30+
var_dump($urlValidator->validate($wrongUrl, $urlConstraint));
31+
32+
Reproducing Complex Bugs
33+
------------------------
34+
35+
If the bug is related to the Symfony Framework or if it's too complex to create
36+
a PHP script, it's better to reproduce the bug by forking the Symfony Standard
37+
edition. To do so:
38+
39+
#. Go to https://github.com/symfony/symfony-standard and click on the **Fork**
40+
button to make a fork of that repository or go to your already forked copy.
41+
#. Clone the forked repository into your computer:
42+
``git clone git://github.com/YOUR-GITHUB-USERNAME/symfony-standard.git``
43+
#. Browse the project and create a new branch (e.g. ``issue_23567``,
44+
``reproduce_23657``, etc.)
45+
#. Now you must add the minimum amount of code to reproduce the bug. This is the
46+
trickiest part and it's explained a bit more later.
47+
#. Add, commit and push all your changes.
48+
#. Add a comment in your original issue report to share the URL of your forked
49+
project (e.g. ``https://github.com/YOUR-GITHUB-USERNAME/symfony-standard/tree/issue_23567``)
50+
and, if necessary, explain the steps to reproduce (e.g. "browse this URL",
51+
"fill in this data in the form and submit it", etc.)
52+
53+
Adding the Minimum Amount of Code Possible
54+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55+
56+
The key to create a bug reproducer is to solely focus on the feature that you
57+
suspect is failing. For example, imagine that you suspect that the bug is related
58+
to a route definition. Then, after forking the Symfony Standard Edition:
59+
60+
#. Don't edit any of the default Symfony configuration options.
61+
#. Don't copy your original application code and don't use the same structure
62+
of bundles, controllers, actions, etc. as in your original application.
63+
#. Open the default controller class of the AppBundle and add your routing
64+
definition using annotations.
65+
#. Don't create or modify any other file.
66+
#. Execute the ``server:run`` command and browse the previously defined route
67+
to see if the bug appears or not.
68+
#. If you can see the bug, you're done and you can already share the code with us.
69+
#. If you can't see the bug, you must keep making small changes. For example, if
70+
your original route was defined using XML, forget about the previous route
71+
annotation and define the route using XML instead. Or maybe your application
72+
uses bundle inheritance and that's where the real bug is. Then, forget about
73+
AppBundle and quickly generate a new AppParentBundle, make AppBundle inherit
74+
from it and test if the route is working.
75+
76+
In short, the idea is to keep adding small and incremental changes to the default
77+
Symfony Standard edition until you can reproduce the bug.

deployment/platformsh.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -186,8 +186,8 @@ soon be able to see it in your browser.
186186

187187
.. _`Platform.sh`: https://platform.sh
188188
.. _`Platform.sh documentation`: https://docs.platform.sh/frameworks/symfony.html
189-
.. _`Platform.sh project`: https://marketplace.commerceguys.com/platform/buy-now
190-
.. _`Platform.sh configuration files`: https://docs.platform.sh/reference/configuration-files
189+
.. _`Platform.sh project`: https://accounts.platform.sh/platform/buy-now
190+
.. _`Platform.sh configuration files`: https://docs.platform.sh/configuration/services.html
191191
.. _`GitHub`: https://github.com/platformsh/platformsh-examples
192192
.. _`available services`: https://docs.platform.sh/reference/configuration-files/#configure-services
193-
.. _`migrating your database and files`: https://docs.platform.sh/toolstacks/php/symfony/migrate-existing-site/
193+
.. _`migrating your database and files`: https://docs.platform.sh/tutorials/migrating.html

form/action_method.rst

Lines changed: 92 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,31 +9,108 @@ URL under which the form was rendered. Sometimes you want to change these
99
parameters. You can do so in a few different ways.
1010

1111
If you use the :class:`Symfony\\Component\\Form\\FormBuilder` to build your
12-
form, you can use ``setAction()`` and ``setMethod()``::
12+
form, you can use ``setAction()`` and ``setMethod()``:
1313

14-
$form = $this->createFormBuilder($task)
15-
->setAction($this->generateUrl('target_route'))
16-
->setMethod('GET')
17-
->add('task', TextType::class)
18-
->add('dueDate', DateType::class)
19-
->add('save', SubmitType::class)
20-
->getForm();
14+
.. configuration-block::
15+
16+
.. code-block:: php-symfony
17+
18+
// AppBundle/Controller/DefaultController.php
19+
namespace AppBundle\Controller;
20+
21+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
22+
use Symfony\Component\Form\Extension\Core\Type\DateType;
23+
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
24+
use Symfony\Component\Form\Extension\Core\Type\TextType;
25+
26+
class DefaultController extends Controller
27+
{
28+
public function newAction()
29+
{
30+
$form = $this->createFormBuilder($task)
31+
->setAction($this->generateUrl('target_route'))
32+
->setMethod('GET')
33+
->add('task', TextType::class)
34+
->add('dueDate', DateType::class)
35+
->add('save', SubmitType::class)
36+
->getForm();
37+
38+
// ...
39+
}
40+
}
41+
42+
.. code-block:: php-standalone
43+
44+
use Symfony\Component\Form\Forms;
45+
use Symfony\Component\Form\Extension\Core\Type\DateType;
46+
use Symfony\Component\Form\Extension\Core\Type\FormType;
47+
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
48+
use Symfony\Component\Form\Extension\Core\Type\TextType;
49+
50+
// ...
51+
52+
$formFactoryBuilder = Forms::createFormFactoryBuilder();
53+
54+
// Form factory builder configuration ...
55+
56+
$formFactory = $formFactoryBuilder->getFormFactory();
57+
58+
$form = $formFactory->createBuilder(FormType::class, $task)
59+
->setAction($this->generateUrl('target_route'))
60+
->setMethod('GET')
61+
->add('task', TextType::class)
62+
->add('dueDate', DateType::class)
63+
->add('save', SubmitType::class)
64+
->getForm();
2165
2266
.. note::
2367

2468
This example assumes that you've created a route called ``target_route``
2569
that points to the controller that processes the form.
2670

2771
When using a form type class, you can pass the action and method as form
28-
options::
72+
options:
2973

30-
use AppBundle\Form\TaskType;
31-
// ...
74+
.. configuration-block::
75+
76+
.. code-block:: php-symfony
77+
78+
// AppBundle/Controller/DefaultController.php
79+
namespace AppBundle\Controller;
80+
81+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
82+
use AppBundle\Form\TaskType;
83+
84+
class DefaultController extends Controller
85+
{
86+
public function newAction()
87+
{
88+
// ...
89+
90+
$form = $this->createForm(TaskType::class, $task, array(
91+
'action' => $this->generateUrl('target_route'),
92+
'method' => 'GET',
93+
));
94+
95+
// ...
96+
}
97+
}
3298
33-
$form = $this->createForm(TaskType::class, $task, array(
34-
'action' => $this->generateUrl('target_route'),
35-
'method' => 'GET',
36-
));
99+
.. code-block:: php-standalone
100+
101+
use Symfony\Component\Form\Forms;
102+
use AppBundle\Form\TaskType;
103+
104+
$formFactoryBuilder = Forms::createFormFactoryBuilder();
105+
106+
// Form factory builder configuration ...
107+
108+
$formFactory = $formFactoryBuilder->getFormFactory();
109+
110+
$form = $formFactory->create(TaskType::class, $task, array(
111+
'action' => $this->generateUrl('target_route'),
112+
'method' => 'GET',
113+
));
37114
38115
Finally, you can override the action and method in the template by passing them
39116
to the ``form()`` or the ``form_start()`` helper functions:

http_cache.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ cache system.
2727

2828
Since caching with HTTP isn't unique to Symfony, many articles already exist
2929
on the topic. If you're new to HTTP caching, Ryan Tomayko's article
30-
`Things Caches Do`_ is *highly* recommended . Another in-depth resource is Mark
30+
`Things Caches Do`_ is *highly* recommended. Another in-depth resource is Mark
3131
Nottingham's `Cache Tutorial`_.
3232

3333
.. index::
@@ -53,7 +53,7 @@ Along the way, the cache will store each response that is deemed "cacheable"
5353
the cache sends the cached response to the client, ignoring your application
5454
entirely.
5555

56-
This type of cache is known as a HTTP gateway cache and many exist such
56+
This type of cache is known as an HTTP gateway cache and many exist such
5757
as `Varnish`_, `Squid in reverse proxy mode`_, and the Symfony reverse proxy.
5858

5959
.. tip::

http_cache/expiration.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,5 +85,12 @@ the lifetime calculation vulnerable to clock skew. Another limitation
8585
of the ``Expires`` header is that the specification states that "HTTP/1.1
8686
servers should not send ``Expires`` dates more than one year in the future."
8787

88+
.. note::
89+
90+
According to `RFC 7234 - Caching`_, the ``Expires`` header value is ignored
91+
when the ``s-maxage`` or ``max-age`` directive of the ``Cache-Control``
92+
header is defined.
93+
8894
.. _`expiration model`: http://tools.ietf.org/html/rfc2616#section-13.2
8995
.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html
96+
.. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234#section-4.2.1

performance.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ real and absolute file system paths. This increases the performance for
7979
applications like Symfony that open many PHP files, especially on Windows
8080
systems.
8181

82-
By default PHP sets a ``realpath_cache_size`` of ``16K`` which is too low for
82+
By default, PHP sets a ``realpath_cache_size`` of ``16K`` which is too low for
8383
Symfony. Consider updating this value at least to ``4096K``. In addition, cached
8484
paths are only stored for ``120`` seconds by default. Consider updating this
8585
value too using the ``realpath_cache_ttl`` option:
@@ -195,7 +195,7 @@ Bootstrap Files and Byte Code Caches
195195
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
196196

197197
Even when using a byte code cache, performance will improve when using a bootstrap
198-
file since there will be fewer files to monitor for changes. Of course if this
198+
file since there will be fewer files to monitor for changes. Of course, if this
199199
feature is disabled in the byte code cache (e.g. ``apc.stat=0`` in APC), there
200200
is no longer a reason to use a bootstrap file.
201201

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ configure the value that will be sent in the API request).
1414
This can be a callable or a property path. See `choice_label`_ for similar usage.
1515
If ``null`` is used, an incrementing integer is used as the name.
1616
17+
If you are using a callable to populate ``choice_value``, you need to check
18+
for the case that the value of the field may be ``null``.
19+
1720
.. caution::
1821
1922
In Symfony 2.7, there was a small backwards-compatibility break with how the

reference/requirements.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ Required
2828

2929
.. caution::
3030

31-
Be aware that Symfony has some known limitations when using PHP 5.3.16.
32-
For more information see the `Requirements section of the README`_.
31+
Be aware that PHP 5.3.16 is not suitable to run Symfony,
32+
because of a `major bug in the Reflection subsystem`_.
3333

3434
Optional
3535
--------
@@ -59,3 +59,4 @@ to use.
5959
.. _`Requirements section of the README`: https://github.com/symfony/symfony/blob/2.8/README.md#requirements
6060
.. _`JSON extension`: https://php.net/manual/book.json.php
6161
.. _`ctype extension`: https://php.net/manual/book.ctype.php
62+
.. _`major bug in the Reflection subsystem`: https://bugs.php.net/bug.php?id=62715

0 commit comments

Comments
 (0)