Skip to content

Commit 5fb6d21

Browse files
weaverryanweaverryan
committed
Merge branch '2.4'
2 parents 27b3410 + de03953 commit 5fb6d21

13 files changed

+193
-8
lines changed

‎cookbook/bundles/extension.rst

+5
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,11 @@ The second method has several specific advantages:
8989
supported configuration settings for which backward compatibility will
9090
be maintained.
9191

92+
.. seealso::
93+
94+
For parameter handling within a Dependency Injection class see
95+
:doc:`</cookbook/configuration/using_parameters_in_dic>`.
96+
9297
.. index::
9398
single: Bundle; Extension
9499
single: DependencyInjection; Extension

‎cookbook/configuration/apache_router.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. index::
2-
single: Apache Router
2+
single: Apache Router
33

44
How to use the Apache Router
55
============================

‎cookbook/configuration/environments.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. index::
2-
single: Environments
2+
single: Environments
33

44
How to Master and Create new Environments
55
=========================================

‎cookbook/configuration/external_parameters.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. index::
2-
single: Environments; External parameters
2+
single: Environments; External parameters
33

44
How to Set External Parameters in the Service Container
55
=======================================================

‎cookbook/configuration/front_controllers_and_kernel.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. index::
2-
single: How front controller, ``AppKernel`` and environments
3-
work together
2+
single: How the front controller, ``AppKernel`` and environments
3+
work together
44

55
Understanding how the Front Controller, Kernel and Environments work together
66
=============================================================================

‎cookbook/configuration/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Configuration
66

77
environments
88
override_dir_structure
9+
using_parameters_in_dic
910
front_controllers_and_kernel
1011
external_parameters
1112
pdo_session_storage

‎cookbook/configuration/override_dir_structure.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. index::
2-
single: Override Symfony
2+
single: Override Symfony
33

44
How to override Symfony's Default Directory Structure
55
=====================================================

‎cookbook/configuration/pdo_session_storage.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. index::
2-
single: Session; Database Storage
2+
single: Session; Database Storage
33

44
How to use PdoSessionHandler to store Sessions in the Database
55
==============================================================

‎cookbook/configuration/using_parameters_in_dic.rst

+159
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
.. index::
2+
single: Using Parameters within a Dependency Injection Class
3+
4+
Using Parameters within a Dependency Injection Class
5+
----------------------------------------------------
6+
7+
You have seen how to use configuration parameters within
8+
:ref:`Symfony service containers <book-service-container-parameters>`.
9+
There are special cases such as when you want, for instance, to use the
10+
``%kernel.debug%`` parameter to make the services in your bundle enter
11+
debug mode. For this case there is more work to do in order
12+
to make the system understand the parameter value. By default
13+
your parameter ``%kernel.debug%`` will be treated as a
14+
simple string. Consider this example with the AcmeDemoBundle::
15+
16+
// Inside Configuration class
17+
$rootNode
18+
->children()
19+
->booleanNode('logging')->defaultValue('%kernel.debug%')->end()
20+
// ...
21+
->end()
22+
;
23+
24+
// Inside the Extension class
25+
$config = $this->processConfiguration($configuration, $configs);
26+
var_dump($config['logging']);
27+
28+
Now, examine the results to see this closely:
29+
30+
.. configuration-block::
31+
32+
.. code-block:: yaml
33+
34+
my_bundle:
35+
logging: true
36+
# true, as expected
37+
38+
my_bundle:
39+
logging: %kernel.debug%
40+
# true/false (depends on 2nd parameter of AppKernel),
41+
# as expected, because %kernel.debug% inside configuration
42+
# gets evaluated before being passed to the extension
43+
44+
my_bundle: ~
45+
# passes the string "%kernel.debug%".
46+
# Which is always considered as true.
47+
# The Configurator does not know anything about
48+
# "%kernel.debug%" being a parameter.
49+
50+
.. code-block:: xml
51+
52+
<?xml version="1.0" encoding="UTF-8" ?>
53+
<container xmlns="http://symfony.com/schema/dic/services"
54+
xmlns:my-bundle="http://example.org/schema/dic/my_bundle">
55+
56+
<my-bundle:config logging="true" />
57+
<!-- true, as expected -->
58+
59+
<my-bundle:config logging="%kernel.debug%" />
60+
<!-- true/false (depends on 2nd parameter of AppKernel),
61+
as expected, because %kernel.debug% inside configuration
62+
gets evaluated before being passed to the extension -->
63+
64+
<my-bundle:config />
65+
<!-- passes the string "%kernel.debug%".
66+
Which is always considered as true.
67+
The Configurator does not know anything about
68+
"%kernel.debug%" being a parameter. -->
69+
</container>
70+
71+
.. code-block:: php
72+
73+
$container->loadFromExtension('my_bundle', array(
74+
'logging' => true,
75+
// true, as expected
76+
)
77+
);
78+
79+
$container->loadFromExtension('my_bundle', array(
80+
'logging' => "%kernel.debug%",
81+
// true/false (depends on 2nd parameter of AppKernel),
82+
// as expected, because %kernel.debug% inside configuration
83+
// gets evaluated before being passed to the extension
84+
)
85+
);
86+
87+
$container->loadFromExtension('my_bundle');
88+
// passes the string "%kernel.debug%".
89+
// Which is always considered as true.
90+
// The Configurator does not know anything about
91+
// "%kernel.debug%" being a parameter.
92+
93+
In order to support this use case, the ``Configuration`` class has to
94+
be injected with this parameter via the extension as follows::
95+
96+
namespace Acme\DemoBundle\DependencyInjection;
97+
98+
use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
99+
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
100+
use Symfony\Component\Config\Definition\ConfigurationInterface;
101+
102+
class Configuration implements ConfigurationInterface
103+
{
104+
private $debug;
105+
106+
public function __construct($debug)
107+
{
108+
$this->debug = (Boolean) $debug;
109+
}
110+
111+
public function getConfigTreeBuilder()
112+
{
113+
$treeBuilder = new TreeBuilder();
114+
$rootNode = $treeBuilder->root('acme_demo');
115+
116+
$rootNode
117+
->children()
118+
// ...
119+
->booleanNode('logging')->defaultValue($this->debug)->end()
120+
// ...
121+
->end()
122+
;
123+
124+
return $treeBuilder;
125+
}
126+
}
127+
128+
And set it in the constructor of ``Configuration`` via the ``Extension`` class::
129+
130+
namespace Acme\DemoBundle\DependencyInjection;
131+
132+
use Symfony\Component\DependencyInjection\ContainerBuilder;
133+
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
134+
use Symfony\Component\HttpKernel\DependencyInjection\Extension;
135+
use Symfony\Component\Config\FileLocator;
136+
137+
class AcmeDemoExtension extends Extension
138+
{
139+
// ...
140+
141+
public function getConfiguration(array $config, ContainerBuilder $container)
142+
{
143+
return new Configuration($container->getParameter('kernel.debug'));
144+
}
145+
}
146+
147+
.. sidebar:: Setting the Default in the Extension
148+
149+
There are some instances of ``%kernel.debug%`` usage within a ``Configurator``
150+
class in TwigBundle and AsseticBundle, however this is because the default
151+
parameter value is set by the Extension class. For example in AsseticBundle,
152+
you can find::
153+
154+
$container->setParameter('assetic.debug', $config['debug']);
155+
156+
The string ``%kernel.debug%`` passed here as an argument handles the
157+
interpreting job to the container which in turn does the evaluation.
158+
Both ways accomplish similar goals. AsseticBundle will not use
159+
``%kernel.debug%`` but rather the new ``%assetic.debug%`` parameter.

‎cookbook/configuration/web_server_configuration.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.. index::
2-
single: Web Server
2+
single: Web Server
33

44
Configuring a web server
55
========================

‎cookbook/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424

2525
* :doc:`/cookbook/configuration/environments`
2626
* :doc:`/cookbook/configuration/override_dir_structure`
27+
* :doc:`/cookbook/configuration/using_parameters_in_dic`
2728
* :doc:`/cookbook/configuration/front_controllers_and_kernel`
2829
* :doc:`/cookbook/configuration/external_parameters`
2930
* :doc:`/cookbook/configuration/pdo_session_storage`

‎cookbook/routing/service_container_parameters.rst

+5
Original file line numberDiff line numberDiff line change
@@ -124,3 +124,8 @@ path):
124124
However, as the ``%`` characters included in any URL are automatically encoded,
125125
the resulting URL of this example would be ``/score-50%25`` (``%25`` is the
126126
result of encoding the ``%`` character).
127+
128+
.. seealso::
129+
130+
For parameter handling within a Dependency Injection class see
131+
:doc:`</cookbook/configuration/using_parameters_in_dic>`.

‎reference/forms/types/entity.rst

+14
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,20 @@ This is the property that should be used for displaying the entities
118118
as text in the HTML element. If left blank, the entity object will be
119119
cast into a string and so must have a ``__toString()`` method.
120120

121+
.. note::
122+
123+
The ``property`` option is the property path used to display the option. So you
124+
can use anything supported by the
125+
:doc:`PropertyAccessor component </components/property_access/introduction>`
126+
127+
For example, if the translations property is actually an associative array of
128+
objects, each with a name property, then you could do this::
129+
130+
$builder->add('gender', 'entity', array(
131+
'class' => 'MyBundle:Gender',
132+
'property' => 'translations[en].name',
133+
));
134+
121135
group_by
122136
~~~~~~~~
123137

0 commit comments

Comments
 (0)