Permalink
Browse files

feature #3420 [Cookbook][Configuration] add configuration cookbook ha…

…ndlig parameters in Configurator class (cordoval)

This PR was merged into the 2.3 branch.

Discussion
----------

[Cookbook][Configuration] add configuration cookbook handlig parameters in Configurator class

| Q             | A                   |
| ---           | ---                 |
| Doc fix?      | yes                 |
| New docs?     | no                  |
| Applies to    | 2.3+                |
| Fixed tickets | #3219               |
| License       | CC-ASA 3.0 Unported |

 Sent using [Gush](https://github.com/cordoval/gush)

Commits
-------

9710bb5 final touches
ad27a83 address comments by xabbuh
a6bda5e address weaverryan comments
28c144a plug xml and php version of the configuration
c07c655 fix see also block
ec13feb plug changes according to comments
243c0d1 create configuration cookbook with ways of handling paramters in Configurator class
  • Loading branch information...
weaverryan committed Mar 18, 2014
2 parents a1050eb + 9710bb5 commit 5965ec809237c5f0aab41b9d53cd928200517216
@@ -89,6 +89,11 @@ The second method has several specific advantages:
supported configuration settings for which backward compatibility will
be maintained.
.. seealso::
For parameter handling within a Dependency Injection class see
:doc:`</cookbook/configuration/using_parameters_in_dic>`.
.. index::
single: Bundle; Extension
single: DependencyInjection; Extension
@@ -1,5 +1,5 @@
.. index::
single: Apache Router
single: Apache Router
How to use the Apache Router
============================
@@ -1,5 +1,5 @@
.. index::
single: Environments
single: Environments
How to Master and Create new Environments
=========================================
@@ -1,5 +1,5 @@
.. index::
single: Environments; External parameters
single: Environments; External parameters
How to Set External Parameters in the Service Container
=======================================================
@@ -1,6 +1,6 @@
.. index::
single: How front controller, ``AppKernel`` and environments
work together
single: How the front controller, ``AppKernel`` and environments
work together
Understanding how the Front Controller, Kernel and Environments work together
=============================================================================
@@ -6,6 +6,7 @@ Configuration
environments
override_dir_structure
using_parameters_in_dic
front_controllers_and_kernel
external_parameters
pdo_session_storage
@@ -1,5 +1,5 @@
.. index::
single: Override Symfony
single: Override Symfony
How to override Symfony's Default Directory Structure
=====================================================
@@ -1,5 +1,5 @@
.. index::
single: Session; Database Storage
single: Session; Database Storage
How to use PdoSessionHandler to store Sessions in the Database
==============================================================
@@ -0,0 +1,159 @@
.. index::
single: Using Parameters within a Dependency Injection Class
Using Parameters within a Dependency Injection Class
----------------------------------------------------
You have seen how to use configuration parameters within
:ref:`Symfony service containers <book-service-container-parameters>`.
There are special cases such as when you want, for instance, to use the
``%kernel.debug%`` parameter to make the services in your bundle enter
debug mode. For this case there is more work to do in order
to make the system understand the parameter value. By default
your parameter ``%kernel.debug%`` will be treated as a
simple string. Consider this example with the AcmeDemoBundle::
// Inside Configuration class
$rootNode
->children()
->booleanNode('logging')->defaultValue('%kernel.debug%')->end()
// ...
->end()
;
// Inside the Extension class
$config = $this->processConfiguration($configuration, $configs);
var_dump($config['logging']);
Now, examine the results to see this closely:
.. configuration-block::
.. code-block:: yaml
my_bundle:
logging: true
# true, as expected
my_bundle:
logging: %kernel.debug%
# true/false (depends on 2nd parameter of AppKernel),
# as expected, because %kernel.debug% inside configuration
# gets evaluated before being passed to the extension
my_bundle: ~
# passes the string "%kernel.debug%".
# Which is always considered as true.
# The Configurator does not know anything about
# "%kernel.debug%" being a parameter.
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:my-bundle="http://example.org/schema/dic/my_bundle">
<my-bundle:config logging="true" />
<!-- true, as expected -->
<my-bundle:config logging="%kernel.debug%" />
<!-- true/false (depends on 2nd parameter of AppKernel),
as expected, because %kernel.debug% inside configuration
gets evaluated before being passed to the extension -->
<my-bundle:config />
<!-- passes the string "%kernel.debug%".
Which is always considered as true.
The Configurator does not know anything about
"%kernel.debug%" being a parameter. -->
</container>
.. code-block:: php
$container->loadFromExtension('my_bundle', array(
'logging' => true,
// true, as expected
)
);
$container->loadFromExtension('my_bundle', array(
'logging' => "%kernel.debug%",
// true/false (depends on 2nd parameter of AppKernel),
// as expected, because %kernel.debug% inside configuration
// gets evaluated before being passed to the extension
)
);
$container->loadFromExtension('my_bundle');
// passes the string "%kernel.debug%".
// Which is always considered as true.
// The Configurator does not know anything about
// "%kernel.debug%" being a parameter.
In order to support this use case, the ``Configuration`` class has to
be injected with this parameter via the extension as follows::
namespace Acme\DemoBundle\DependencyInjection;
use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
use Symfony\Component\Config\Definition\ConfigurationInterface;
class Configuration implements ConfigurationInterface
{
private $debug;
public function __construct($debug)
{
$this->debug = (Boolean) $debug;
}
public function getConfigTreeBuilder()
{
$treeBuilder = new TreeBuilder();
$rootNode = $treeBuilder->root('acme_demo');
$rootNode
->children()
// ...
->booleanNode('logging')->defaultValue($this->debug)->end()
// ...
->end()
;
return $treeBuilder;
}
}
And set it in the constructor of ``Configuration`` via the ``Extension`` class::
namespace Acme\DemoBundle\DependencyInjection;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
use Symfony\Component\HttpKernel\DependencyInjection\Extension;
use Symfony\Component\Config\FileLocator;
class AcmeDemoExtension extends Extension
{
// ...
public function getConfiguration(array $config, ContainerBuilder $container)
{
return new Configuration($container->getParameter('kernel.debug'));
}
}
.. sidebar:: Setting the Default in the Extension
There are some instances of ``%kernel.debug%`` usage within a ``Configurator``
class in TwigBundle and AsseticBundle, however this is because the default
parameter value is set by the Extension class. For example in AsseticBundle,
you can find::
$container->setParameter('assetic.debug', $config['debug']);
The string ``%kernel.debug%`` passed here as an argument handles the
interpreting job to the container which in turn does the evaluation.
Both ways accomplish similar goals. AsseticBundle will not use
anymore ``%kernel.debug%`` but rather the new ``%assetic.debug%`` parameter.
@@ -1,5 +1,5 @@
.. index::
single: Web Server
single: Web Server
Configuring a web server
========================
View
@@ -24,6 +24,7 @@
* :doc:`/cookbook/configuration/environments`
* :doc:`/cookbook/configuration/override_dir_structure`
* :doc:`/cookbook/configuration/using_parameters_in_dic`
* :doc:`/cookbook/configuration/front_controllers_and_kernel`
* :doc:`/cookbook/configuration/external_parameters`
* :doc:`/cookbook/configuration/pdo_session_storage`
@@ -124,3 +124,8 @@ path):
However, as the ``%`` characters included in any URL are automatically encoded,
the resulting URL of this example would be ``/score-50%25`` (``%25`` is the
result of encoding the ``%`` character).
.. seealso::
For parameter handling within a Dependency Injection class see
:doc:`</cookbook/configuration/using_parameters_in_dic>`.

0 comments on commit 5965ec8

Please sign in to comment.