From 6f38035b786fa8bc35c1b922fb15042e97194200 Mon Sep 17 00:00:00 2001 From: Richard Miller Date: Wed, 19 Sep 2012 22:44:15 +0100 Subject: [PATCH 1/2] Adding an overview of how the service container concepts fit togther --- .../dependency_injection/compilation.rst | 6 ++ .../dependency_injection/introduction.rst | 2 + components/dependency_injection/workflow.rst | 74 +++++++++++++++++++ 3 files changed, 82 insertions(+) create mode 100644 components/dependency_injection/workflow.rst diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst index 02a47e279d1..d91ff529959 100644 --- a/components/dependency_injection/compilation.rst +++ b/components/dependency_injection/compilation.rst @@ -22,6 +22,8 @@ validity, further compiler passes are used to optimize the configuration before it is cached. For example, private services and abstract services are removed, and aliases are resolved. +.. _components-dependency-injection-extension: + Managing Configuration with Extensions -------------------------------------- @@ -238,6 +240,8 @@ but also load a secondary one only if a certain parameter is set:: You should instead use a compiler pass which works with the full container after the extensions have been processed. +.. _components-dependency-injection-compiler-passes: + Creating a Compiler Pass ------------------------ @@ -307,6 +311,8 @@ For example, to run your custom pass after the default removal passes have been $container = new ContainerBuilder(); $container->addCompilerPass(new CustomCompilerPass, PassConfig::TYPE_AFTER_REMOVING); +.. _components-dependency-injection-dumping: + Dumping the Configuration for Performance ----------------------------------------- diff --git a/components/dependency_injection/introduction.rst b/components/dependency_injection/introduction.rst index 73f114f9673..5154a5c9d27 100644 --- a/components/dependency_injection/introduction.rst +++ b/components/dependency_injection/introduction.rst @@ -194,6 +194,8 @@ difficult to reuse the class elsewhere. You will need to get a service from the container at some point but this should be as few times as possible at the entry point to your application. +.. _components-dependency-injection-loading-config: + Setting Up the Container with Configuration Files ------------------------------------------------- diff --git a/components/dependency_injection/workflow.rst b/components/dependency_injection/workflow.rst new file mode 100644 index 00000000000..8312d312ec6 --- /dev/null +++ b/components/dependency_injection/workflow.rst @@ -0,0 +1,74 @@ +.. index:: + single: Dependency Injection; Workflow + +Container Building Workflow +=========================== + +In the preceding pages of this section of the components there has been +little to say where the various files and classes should be located. This +is because this depends on the application, library or framework you want +to use the container in. Looking at how the container is configured and built +in the Symfony2 full stack framework will help you see how this all fits +together whether you are using the full stack framework or looking to use +the service container in another application. + +The full stack framework uses the ``HTTPKernel`` component to manage the loading +of service container configuration from the app level and from bundles as well +as with the compilation and caching. Even if you are not using the ``HTTPKernel`` +it should give you an idea of a way of organising configuration in a modular +application. + +Working with cached controller +------------------------------ + +Before building the container a cached version is checked for. The ``HTTPKernel`` +has a debug setting, if this is false then the cached version is used if it +exists. If debug is true then the cached configuration is checked for freshness +and the cached version of the container used if it is. If not then the container +is built from the app level configuration and the bundle's extension configuration. +Read :ref:`Dumping the Configuration for Performance` +for more details. + +Application level configuration +------------------------------- + +Application level config is loaded from the ``app/config`` directory. Multiple +files are loaded which are then merged when the Extensions are processed. This +allows for different config for different environments e.g. dev, prod. + +These files contain parameters and services to be be loaded directly into +the container as per :ref:`Setting Up the Container with Configuration Files`. +They all contain config to be processed by Extensions as per :ref:`Managing Configuration with Extensions`. +These are considered to be bundle configuration since each bundle contains +an Extension class. + +Bundle level config with extensions +----------------------------------- + +By convention each bundle contains an Extension class which is in the bundle's +Dependency Injection directory. These are registered with the ``ContainerBuilder`` +when the Kernel is booted. When the ContainerBundle is :doc:`compiled` +the app level config relevant to the bundle's extension is passed to the Extension +which also usually loads its own config file(s), typically from the bundle's +``Resources/config`` directory. The app level config is usually processed with +a Configuration object also stored in the bundle's ``DependencyInjection`` +directory. + +Compiler passes to allow interaction between bundles +---------------------------------------------------- + +:ref:`Compiler passes` are +used to allow interaction between different bundles as they cannot affect +each others configuration in the extension classes. One of the main uses is +to process tagged services, allowing bundles to register services to picked +up by other bundle, such as Monolog loggers, Twig extensions and Data Collectors +for the Web Profiler. Compiler passes are usually placed in the bundle's +``DependencyInjection/Compiler`` directory. + +Compilation and caching +----------------------- + +After the compilation process has loaded the services from the configuration, +extensions and the compiler passes it is dumped so that the cache can be used +next time and the dumped version then used during the request as it is more +efficient. From d56d2ea03212eb582e68a5c64d547c734722c8e5 Mon Sep 17 00:00:00 2001 From: Richard Miller Date: Thu, 20 Sep 2012 07:41:13 +0100 Subject: [PATCH 2/2] Fixing some errors in di workflow page --- components/dependency_injection/workflow.rst | 24 ++++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/components/dependency_injection/workflow.rst b/components/dependency_injection/workflow.rst index 8312d312ec6..512ae117aca 100644 --- a/components/dependency_injection/workflow.rst +++ b/components/dependency_injection/workflow.rst @@ -12,18 +12,18 @@ in the Symfony2 full stack framework will help you see how this all fits together whether you are using the full stack framework or looking to use the service container in another application. -The full stack framework uses the ``HTTPKernel`` component to manage the loading +The full stack framework uses the ``HttpKernel`` component to manage the loading of service container configuration from the app level and from bundles as well -as with the compilation and caching. Even if you are not using the ``HTTPKernel`` +as with the compilation and caching. Even if you are not using the ``HttpKernel`` it should give you an idea of a way of organising configuration in a modular application. -Working with cached controller ------------------------------- +Working with cached container +----------------------------- -Before building the container a cached version is checked for. The ``HTTPKernel`` +Before building the container a cached version is checked for. The ``HttpKernel`` has a debug setting, if this is false then the cached version is used if it -exists. If debug is true then the cached configuration is checked for freshness +exists. If debug is true then the :doc:`cached configuration is checked for freshness` and the cached version of the container used if it is. If not then the container is built from the app level configuration and the bundle's extension configuration. Read :ref:`Dumping the Configuration for Performance` @@ -33,12 +33,12 @@ Application level configuration ------------------------------- Application level config is loaded from the ``app/config`` directory. Multiple -files are loaded which are then merged when the Extensions are processed. This +files are loaded which are then merged when the extensions are processed. This allows for different config for different environments e.g. dev, prod. -These files contain parameters and services to be be loaded directly into +These files contain parameters and services to be loaded directly into the container as per :ref:`Setting Up the Container with Configuration Files`. -They all contain config to be processed by Extensions as per :ref:`Managing Configuration with Extensions`. +They all contain config to be processed by extensions as per :ref:`Managing Configuration with Extensions`. These are considered to be bundle configuration since each bundle contains an Extension class. @@ -47,12 +47,12 @@ Bundle level config with extensions By convention each bundle contains an Extension class which is in the bundle's Dependency Injection directory. These are registered with the ``ContainerBuilder`` -when the Kernel is booted. When the ContainerBundle is :doc:`compiled` +when the Kernel is booted. When the ContainerBuilder is :doc:`compiled` the app level config relevant to the bundle's extension is passed to the Extension which also usually loads its own config file(s), typically from the bundle's ``Resources/config`` directory. The app level config is usually processed with -a Configuration object also stored in the bundle's ``DependencyInjection`` -directory. +a :doc:`Configuration object` also stored in the +bundle's ``DependencyInjection`` directory. Compiler passes to allow interaction between bundles ----------------------------------------------------