From 675492e1b433f51b7f41df15fe8876286caf2e4a Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Thu, 4 Apr 2013 09:52:01 +0200 Subject: [PATCH 1/7] Add a new section on front controllers and the AppKernel --- .../front_controllers_and_kernel.rst | 117 ++++++++++++++++++ cookbook/configuration/index.rst | 1 + 2 files changed, 118 insertions(+) create mode 100644 cookbook/configuration/front_controllers_and_kernel.rst diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst new file mode 100644 index 00000000000..bd650b3d732 --- /dev/null +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -0,0 +1,117 @@ +Understanding how Front Controller, Kernel and Environments work together +========================================================================= + +The previous section, understanding and mastering environments, +explained the basics on how Symfony uses environments to run your application +with different configuration settings. This section will explain a bit more +in-depth what happens when your application is bootstrapped and how the +environment it runs in is made up. + +To fully control this environment, you need to understand three parts that +work together: +* The front controller +* The Kernel class +* The environment + +The front controller +==================== + +A *front controller* is a well-known design pattern; it is a section of +code that *all* requests served by an application run through. + +In the Symfony Standard Edition, this role is taken by the ``app.php`` and +``app_dev.php`` files in the ``web/`` directory. These are the very first PHP +scripts executed when a request is processed. + +The main purpose of the front controller is to create an instance of the +``AppKernel`` (more on that in a second), make it handle the request and +return the resulting response to the browser. + +Because every request is routed through it, the front controller can be used +to perform global initializations prior to setting up the kernel or to +*decorate* the kernel with additional features. Examples include: +* Configure the autoloader or add additional autoloading mechanisms +* Add HTTP level caching by wrapping the kernel with an instance of AppCache +(http://symfony.com/doc/2.0/book/http_cache.html#symfony2-reverse-proxy) +* Enabling the Debug component (add link) + +When using Apache and the RewriteRule (https://github +.com/symfony/symfony-standard/blob/master/web/.htaccess) shipped with the +Standard Edition, the front controller can be chosen by requesting URLs like + + http://localhost/app_dev.php/some/path/... + +As you can see, this URL contains the PHP script to be used as +the front controller. You can use that to easily switch the front controller +or use a custom one by placing it in the ``web/`` directory. If the front +controller file is missing from the URL, the RewriteRule will use ``app +.php`` as the default one. + +Technically, the ``app/console`` script (https://github +.com/symfony/symfony-standard/blob/master/app/console) used when running +Symfony on the command line is also a front controller, +only that is not used for web, but for command line requests. + +The AppKernel +============= + +The Kernel object is the core of Symfony2. The Kernel is responsible for +setting up all the bundles that make up your application and providing them +with the application's configuration. It then creates the service container +before serving requests in its ``handle()`` method. + +There are two methods related to the first two of these steps which the base +HttpKernel +(https://github +.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernel +.php) does not implement: + +* ``registerBundles()``, which must return an array of all bundles needed to +run the application; +* ``registerContainerConfiguration()``, which loads the application +configuration. + +The Symfony2 Standard Edition comes with a so-called ``AppKernel`` in the +``app/`` directory (https://github +.com/symfony/symfony-standard/blob/master/app/AppKernel.php) which fills +these blanks. This class +uses the name of the environment, which is passed into the Kernel's +``__construct()`` method and is available via ``getEnvironment()``, +to decide which bundles to create in ``registerBundles()``. This method is +meant to be extended by you when you start adding bundles to your application. + +You are, of course, free to create alternative or additional +``AppKernel`` variants. All you need is to adapt (or add a) your front +controller script to make use of the new kernel. Adding additional kernel +implementations might be useful to +* easily switch between different set of bundles to work with (without +creating too complicated ``if...else...`` constructs in the ``registerBundles +()`` method +* add more sophisticated ways of loading the application's configuration from + a different set of files. + +The environments +================ + +Environments have been covered extensively in the previous chapter (add link). +You probably remember that an environment is nothing more than a name (a +string) passed to the Kernel's constructor which is in turn used to +determine which set of configuration files the Kernel is supposed to load. + +For that, the Standard Edition's ``AppKernel`` class implements the +``registerContainerConfiguration()`` method to load the +``app/config/config_*environment*.yml`` file. + + + + + + + + + + + + + + diff --git a/cookbook/configuration/index.rst b/cookbook/configuration/index.rst index 3ca24b01bd4..0d6c51a9027 100644 --- a/cookbook/configuration/index.rst +++ b/cookbook/configuration/index.rst @@ -5,6 +5,7 @@ Configuration :maxdepth: 2 environments + front_controllers_and_kernel override_dir_structure external_parameters pdo_session_storage From ad568ec786baf529f614814c0f9ac0a0317bb272 Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Thu, 4 Apr 2013 09:56:32 +0200 Subject: [PATCH 2/7] Some updates --- .../front_controllers_and_kernel.rst | 86 ++++++++----------- 1 file changed, 34 insertions(+), 52 deletions(-) diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst index bd650b3d732..d4d42624056 100644 --- a/cookbook/configuration/front_controllers_and_kernel.rst +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -1,14 +1,12 @@ Understanding how Front Controller, Kernel and Environments work together ========================================================================= -The previous section, understanding and mastering environments, +The section :doc:`/cookbook/configuration/environments` explained the basics on how Symfony uses environments to run your application with different configuration settings. This section will explain a bit more -in-depth what happens when your application is bootstrapped and how the -environment it runs in is made up. - -To fully control this environment, you need to understand three parts that +in-depth what happens when your application is bootstrapped and how you can hook into this process. You need to understand three parts that work together: + * The front controller * The Kernel class * The environment @@ -16,11 +14,11 @@ work together: The front controller ==================== -A *front controller* is a well-known design pattern; it is a section of +The [`front controller`](http://en.wikipedia.org/wiki/Front_Controller_pattern) is a well-known design pattern; it is a section of code that *all* requests served by an application run through. -In the Symfony Standard Edition, this role is taken by the ``app.php`` and -``app_dev.php`` files in the ``web/`` directory. These are the very first PHP +In the [Symfony 2 Standard Edition](https://github.com/symfony/symfony-standard), this role is taken by the [``app.php``](https://github.com/symfony/symfony-standard/blob/master/web/app.php) and +[``app_dev.php``](https://github.com/symfony/symfony-standard/blob/master/web/app_dev.php) files in the ``web/`` directory. These are the very first PHP scripts executed when a request is processed. The main purpose of the front controller is to create an instance of the @@ -29,15 +27,15 @@ return the resulting response to the browser. Because every request is routed through it, the front controller can be used to perform global initializations prior to setting up the kernel or to -*decorate* the kernel with additional features. Examples include: +[*decorate*](http://en.wikipedia.org/wiki/Decorator_pattern) the kernel with additional features. Examples include: + * Configure the autoloader or add additional autoloading mechanisms -* Add HTTP level caching by wrapping the kernel with an instance of AppCache -(http://symfony.com/doc/2.0/book/http_cache.html#symfony2-reverse-proxy) -* Enabling the Debug component (add link) +* Add HTTP level caching by wrapping the kernel with an instance of :doc:`AppCache` +* Enabling the [Debug component](https://github.com/symfony/symfony/pull/7441) -When using Apache and the RewriteRule (https://github -.com/symfony/symfony-standard/blob/master/web/.htaccess) shipped with the -Standard Edition, the front controller can be chosen by requesting URLs like +When using Apache and the [RewriteRule shipped with the +Standard Edition](https://github +.com/symfony/symfony-standard/blob/master/web/.htaccess), the front controller can be chosen by requesting URLs like:: http://localhost/app_dev.php/some/path/... @@ -47,7 +45,7 @@ or use a custom one by placing it in the ``web/`` directory. If the front controller file is missing from the URL, the RewriteRule will use ``app .php`` as the default one. -Technically, the ``app/console`` script (https://github +Technically, the [``app/console`` script](https://github .com/symfony/symfony-standard/blob/master/app/console) used when running Symfony on the command line is also a front controller, only that is not used for web, but for command line requests. @@ -60,58 +58,42 @@ setting up all the bundles that make up your application and providing them with the application's configuration. It then creates the service container before serving requests in its ``handle()`` method. -There are two methods related to the first two of these steps which the base -HttpKernel -(https://github +There are two methods related to the first two of these steps which [the base +HttpKernel](https://github .com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernel .php) does not implement: -* ``registerBundles()``, which must return an array of all bundles needed to +* :method:`registerBundles()`, which must return an array of all bundles needed to run the application; -* ``registerContainerConfiguration()``, which loads the application +* :method:`registerContainerConfiguration()`, which loads the application configuration. -The Symfony2 Standard Edition comes with a so-called ``AppKernel`` in the -``app/`` directory (https://github -.com/symfony/symfony-standard/blob/master/app/AppKernel.php) which fills -these blanks. This class -uses the name of the environment, which is passed into the Kernel's -``__construct()`` method and is available via ``getEnvironment()``, +To fill these (small) blanks, your application needs to subclass the Kernel +and implement these methods. The resulting class is called the ``AppKernel``. + +Again, the Symfony2 Standard Edition provides an [``AppKernel``](https://github +.com/symfony/symfony-standard/blob/master/app/AppKernel.php) in the +``app/`` directory. This class +uses the name of the environment, which is passed to the Kernel's :method:`constructor` and is available via :method:`getEnvironment()`, to decide which bundles to create in ``registerBundles()``. This method is meant to be extended by you when you start adding bundles to your application. -You are, of course, free to create alternative or additional -``AppKernel`` variants. All you need is to adapt (or add a) your front -controller script to make use of the new kernel. Adding additional kernel +You are, of course, free to create your own, alternative or additional +``AppKernel`` variants. All you need is to adapt your (or add a new) front +controller to make use of the new kernel. Adding additional kernel implementations might be useful to -* easily switch between different set of bundles to work with (without + +* easily switch between different set of bundles to work with, without creating too complicated ``if...else...`` constructs in the ``registerBundles -()`` method +()`` method or * add more sophisticated ways of loading the application's configuration from a different set of files. The environments ================ -Environments have been covered extensively in the previous chapter (add link). -You probably remember that an environment is nothing more than a name (a +Environments have been covered extensively :doc:`in the previous chapter`. You probably remember that an environment is nothing more than a name (a string) passed to the Kernel's constructor which is in turn used to -determine which set of configuration files the Kernel is supposed to load. - -For that, the Standard Edition's ``AppKernel`` class implements the -``registerContainerConfiguration()`` method to load the -``app/config/config_*environment*.yml`` file. - - - - - - - - - - - - - +determine which set of configuration files the Kernel is supposed to load - and this is what the missing :method:`registerContainerConfiguration()` method is used for. +The Standard Edition's [``AppKernel``](https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php) class implements this method by simply loading the ``app/config/config_*environment*.yml`` file. From 3bfbf69086ad199c7e2a6f31b9556d5b5b3c01e3 Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Fri, 5 Apr 2013 00:39:32 +0200 Subject: [PATCH 3/7] Markup fixes and small changes --- .../front_controllers_and_kernel.rst | 170 ++++++++++++------ 1 file changed, 113 insertions(+), 57 deletions(-) diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst index d4d42624056..803ce6c89e7 100644 --- a/cookbook/configuration/front_controllers_and_kernel.rst +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -1,82 +1,119 @@ +.. index:: + single: How front controller, ``AppKernel`` and environments + work together + Understanding how Front Controller, Kernel and Environments work together ========================================================================= The section :doc:`/cookbook/configuration/environments` -explained the basics on how Symfony uses environments to run your application -with different configuration settings. This section will explain a bit more -in-depth what happens when your application is bootstrapped and how you can hook into this process. You need to understand three parts that -work together: +explained the basics on how Symfony uses environments to run your +application with different configuration settings. This section will +explain a bit more in-depth what happens when your application is +bootstrapped. To hook into this process, you need to understand three +parts that work together: * The front controller -* The Kernel class +* The ``Kernel` class * The environment +.. note:: + + Usually, you will not need to define your own front controller or + ``AppKernel`` as the `Symfony 2 Standard Edition`_ provides + sensible default implementations. + + This documentation section is provided for completeness to + explain what is going on behind the scenes. + + The front controller ==================== -The [`front controller`](http://en.wikipedia.org/wiki/Front_Controller_pattern) is a well-known design pattern; it is a section of +The `front controller`_ is a well-known design pattern; it is a +section of code that *all* requests served by an application run through. -In the [Symfony 2 Standard Edition](https://github.com/symfony/symfony-standard), this role is taken by the [``app.php``](https://github.com/symfony/symfony-standard/blob/master/web/app.php) and -[``app_dev.php``](https://github.com/symfony/symfony-standard/blob/master/web/app_dev.php) files in the ``web/`` directory. These are the very first PHP -scripts executed when a request is processed. +In the `Symfony 2 Standard Edition`_, this role is taken by the +``app.php``_ and ``app_dev.php``_ files in the ``web/`` directory. +These are the very first PHP scripts executed when a request is +processed. The main purpose of the front controller is to create an instance of the -``AppKernel`` (more on that in a second), make it handle the request and +``AppKernel`` (more on that in a second), make it handle the reques and return the resulting response to the browser. -Because every request is routed through it, the front controller can be used -to perform global initializations prior to setting up the kernel or to -[*decorate*](http://en.wikipedia.org/wiki/Decorator_pattern) the kernel with additional features. Examples include: +Because every request is routed through it, the front controller can be +used to perform global initializations prior to setting up the kernel or +to *`decorate`_* the kernel with additional features. Examples include: * Configure the autoloader or add additional autoloading mechanisms -* Add HTTP level caching by wrapping the kernel with an instance of :doc:`AppCache` -* Enabling the [Debug component](https://github.com/symfony/symfony/pull/7441) +* Add HTTP level caching by wrapping the kernel with an instance of +:doc:`AppCache` +* Enabling the `Debug component`_ -When using Apache and the [RewriteRule shipped with the -Standard Edition](https://github -.com/symfony/symfony-standard/blob/master/web/.htaccess), the front controller can be chosen by requesting URLs like:: +When using Apache and the `RewriteRule shipped with the +Standard Edition`_, the front controller can be chosen by requesting +URLs like:: - http://localhost/app_dev.php/some/path/... +.. code-block:: text -As you can see, this URL contains the PHP script to be used as -the front controller. You can use that to easily switch the front controller -or use a custom one by placing it in the ``web/`` directory. If the front -controller file is missing from the URL, the RewriteRule will use ``app -.php`` as the default one. + http://localhost/app_dev.php/some/path/... -Technically, the [``app/console`` script](https://github -.com/symfony/symfony-standard/blob/master/app/console) used when running -Symfony on the command line is also a front controller, -only that is not used for web, but for command line requests. +As you can see, this URL contains the PHP script to be used as +the front controller. You can use that to easily switch the front +controller or use a custom one by placing it in the ``web/`` directory. +If the front controller file is missing from the URL, the RewriteRule +will use ``app.php`` as the default one. -The AppKernel -============= +.. note:: -The Kernel object is the core of Symfony2. The Kernel is responsible for -setting up all the bundles that make up your application and providing them -with the application's configuration. It then creates the service container -before serving requests in its ``handle()`` method. + When adding a custom front controller and/or using the + provided RewriteRule in production, make sure to appropriately + secure it agains unauthorized access. -There are two methods related to the first two of these steps which [the base -HttpKernel](https://github -.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernel -.php) does not implement: + For example, you don't want to make the debug toolbar available + to arbitraty users in your production environment. -* :method:`registerBundles()`, which must return an array of all bundles needed to -run the application; -* :method:`registerContainerConfiguration()`, which loads the application -configuration. +Technically, the ``app/console``_ used when running +Symfony on the command line is also a front controller, +only that is not used for web, but for command line requests. -To fill these (small) blanks, your application needs to subclass the Kernel -and implement these methods. The resulting class is called the ``AppKernel``. +The ``AppKernel`` +================= -Again, the Symfony2 Standard Edition provides an [``AppKernel``](https://github -.com/symfony/symfony-standard/blob/master/app/AppKernel.php) in the +The Kernel object is the core of Symfony2. The Kernel is responsible for +setting up all the bundles that make up your application and providing +them with the application's configuration. It then creates the service +container before serving requests in its +:method:`Symfony\\Component\\HttpKernel\\HttpKernelInterface::handle` +method. + +There are two `template methods`_ related to the first two of these +steps which the +:class:`base HttpKernel ` +does not implement: + +* :method:`Symfony\\Component\\HttpKernel\\HttpKernel::registerBundles`, + which must return an array of all bundles needed to + run the application; + +* :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`, + which loads the application configuration. + +To fill these (small) blanks, your application needs to subclass the +Kernel and implement these methods. The resulting class is +conventionally called the ``AppKernel``. + +Again, the Symfony2 Standard Edition provides an ```AppKernel```_ in + the ``app/`` directory. This class -uses the name of the environment, which is passed to the Kernel's :method:`constructor` and is available via :method:`getEnvironment()`, -to decide which bundles to create in ``registerBundles()``. This method is -meant to be extended by you when you start adding bundles to your application. +uses the name of the environment, which is passed to the Kernel's +:method:`constructor` +and is available via +:method:`getEnvironment()`, +to decide which bundles to create in ``registerBundles()``. This method +is meant to be extended by you when you start adding bundles to your +application. You are, of course, free to create your own, alternative or additional ``AppKernel`` variants. All you need is to adapt your (or add a new) front @@ -84,16 +121,35 @@ controller to make use of the new kernel. Adding additional kernel implementations might be useful to * easily switch between different set of bundles to work with, without -creating too complicated ``if...else...`` constructs in the ``registerBundles -()`` method or -* add more sophisticated ways of loading the application's configuration from - a different set of files. + creating too complicated ``if...else...`` constructs in the + :method:`Symfony\\Component\\HttpKernel\\HttpKernel::registerBundles` + method or +* add more sophisticated ways of loading the application's configuration + from a different set of files. The environments ================ -Environments have been covered extensively :doc:`in the previous chapter`. You probably remember that an environment is nothing more than a name (a +Environments have been covered extensively +:doc:`in the previous chapter`. +You probably remember that an environment is nothing more than a name (a string) passed to the Kernel's constructor which is in turn used to -determine which set of configuration files the Kernel is supposed to load - and this is what the missing :method:`registerContainerConfiguration()` method is used for. - -The Standard Edition's [``AppKernel``](https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php) class implements this method by simply loading the ``app/config/config_*environment*.yml`` file. +determine which set of configuration files the Kernel is supposed to +load - and this is what the missing +:method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration` +method is used for. + +The Standard Edition's ``AppKernel``_ class implements this method by +simply loading the ``app/config/config_*environment*.yml`` file. + +.. _front controller: http://en.wikipedia.org/wiki/Front_Controller_pattern +.. _Symfony 2 Standard Edition: https://github.com/symfony/symfony-standard +.. _app.php: https://github.com/symfony/symfony-standard/blob/master/web/app.php +.. _app_dev.php: https://github.com/symfony/symfony-standard/blob/master/web/app_dev.php +.. _app/console: https://github.com/symfony/symfony-standard/blob/master/app/console +.. _AppKernel: https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php +.. _decorate: http://en.wikipedia.org/wiki/Decorator_pattern +.. _Debug Component: https://github.com/symfony/symfony/pull/7441 +.. _RewriteRule shipped with the Standard Edition: https://github.com/symfony/symfony-standard/blob/master/web/.htaccess) +.. _base HTTPKernel: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernel.php +.. _template methods: http://en.wikipedia.org/wiki/Template_method_pattern From 588c344ea5f0b99fd118aff358c761b493a06361 Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Fri, 5 Apr 2013 09:29:13 +0200 Subject: [PATCH 4/7] Even more GH feedback, some additional notes and typos --- .../front_controllers_and_kernel.rst | 79 +++++++++++++------ 1 file changed, 55 insertions(+), 24 deletions(-) diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst index 803ce6c89e7..04c687fd148 100644 --- a/cookbook/configuration/front_controllers_and_kernel.rst +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -39,8 +39,8 @@ These are the very first PHP scripts executed when a request is processed. The main purpose of the front controller is to create an instance of the -``AppKernel`` (more on that in a second), make it handle the reques and -return the resulting response to the browser. +``AppKernel`` (more on that in a second), make it handle the request +and return the resulting response to the browser. Because every request is routed through it, the front controller can be used to perform global initializations prior to setting up the kernel or @@ -67,12 +67,17 @@ will use ``app.php`` as the default one. .. note:: - When adding a custom front controller and/or using the - provided RewriteRule in production, make sure to appropriately - secure it agains unauthorized access. + Pretty much every other web server should be able to achieve a + behavior similar to that of the RewriteRule described above. + Check your server documentation for details. - For example, you don't want to make the debug toolbar available - to arbitraty users in your production environment. +.. note:: + + Make sure you appropriately + secure your front controllers against unauthorized access. + + For example, you don't want to make a debugging environment + available to arbitraty users in your production environment. Technically, the ``app/console``_ used when running Symfony on the command line is also a front controller, @@ -104,7 +109,7 @@ To fill these (small) blanks, your application needs to subclass the Kernel and implement these methods. The resulting class is conventionally called the ``AppKernel``. -Again, the Symfony2 Standard Edition provides an ```AppKernel```_ in +Again, the Symfony2 Standard Edition provides an `AppKernel`_ in the ``app/`` directory. This class uses the name of the environment, which is passed to the Kernel's @@ -117,30 +122,56 @@ application. You are, of course, free to create your own, alternative or additional ``AppKernel`` variants. All you need is to adapt your (or add a new) front -controller to make use of the new kernel. Adding additional kernel -implementations might be useful to +controller to make use of the new kernel. + +.. note:: + + The name and location of the ``AppKernel`` is not fixed. When + putting multiple Kernels into a single application, + it might therefore make sense to add additional sub-directories, + for example ``app/admin/AdminKernel.php`` and + ``app/api/ApiKernel.php``. All that matters is that your front + controller is able to create an instance of the appropriate + kernel. -* easily switch between different set of bundles to work with, without - creating too complicated ``if...else...`` constructs in the - :method:`Symfony\\Component\\HttpKernel\\HttpKernel::registerBundles` - method or -* add more sophisticated ways of loading the application's configuration - from a different set of files. +Having different ``AppKernels`` might be useful to enable different +front controllers (on potentially different servers) to run parts of +your application independently (for example, the admin UI, +the frontend UI and database migrations). + +.. note:: + + There's a lot more the ``AppKernel`` can be used for, + for example :doc:`overriding the default + directory structure + `. But odds are + high that you don't need to change such things on the fly by + having several ``AppKernel`` implementations at hand. The environments ================ +We just mentioned another method the ``AppKernel`` has to implement - +:method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`. +This method is responsible for loading the application's +configuration from the right *environment*. + Environments have been covered extensively -:doc:`in the previous chapter`. -You probably remember that an environment is nothing more than a name (a -string) passed to the Kernel's constructor which is in turn used to -determine which set of configuration files the Kernel is supposed to -load - and this is what the missing +:doc:`in the previous chapter`, + and you probably remember that the Standard Edition comes with three + of them - ``dev``, ``prod`` and ``test``. + +More technically, these names are nothing more than strings passed +from the front controller to the ``AppKernel``'s constructor. This +name can then be used in :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration` -method is used for. +method to decide which configuration files to load. -The Standard Edition's ``AppKernel``_ class implements this method by -simply loading the ``app/config/config_*environment*.yml`` file. +The Standard +Edition's ``AppKernel``_ class implements this method by +simply loading the ``app/config/config_*environment*.yml`` file. You +are, of course, free to implement this method differently if you need + a more sophisticated way of loading your configuration. .. _front controller: http://en.wikipedia.org/wiki/Front_Controller_pattern .. _Symfony 2 Standard Edition: https://github.com/symfony/symfony-standard From b3d459b72294ae59dbe248852bac05711e433dec Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Sat, 6 Apr 2013 01:11:35 +0200 Subject: [PATCH 5/7] GH feedback --- .../front_controllers_and_kernel.rst | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst index 04c687fd148..2ed3011a2fd 100644 --- a/cookbook/configuration/front_controllers_and_kernel.rst +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -30,8 +30,8 @@ The front controller ==================== The `front controller`_ is a well-known design pattern; it is a -section of -code that *all* requests served by an application run through. +section of code that *all* requests served by an application run +through. In the `Symfony 2 Standard Edition`_, this role is taken by the ``app.php``_ and ``app_dev.php``_ files in the ``web/`` directory. @@ -86,21 +86,22 @@ only that is not used for web, but for command line requests. The ``AppKernel`` ================= -The Kernel object is the core of Symfony2. The Kernel is responsible for -setting up all the bundles that make up your application and providing -them with the application's configuration. It then creates the service -container before serving requests in its +The :class:`Symfony\\Component\\HttpKernel\\Kernel` is the core of +Symfony2. It is responsible for setting up all the bundles that make up +your application and providing them with the application's +configuration. It then creates the service container before serving +requests in its :method:`Symfony\\Component\\HttpKernel\\HttpKernelInterface::handle` method. -There are two `template methods`_ related to the first two of these -steps which the -:class:`base HttpKernel ` -does not implement: +There are two methods declared in the +:class:`Symfony\\Component\\HttpKernel\\KernelInterface` that are +left unimplemented in :class:`Symfony\\Component\\HttpKernel\\Kernel` +and thus serve as `template methods`_: -* :method:`Symfony\\Component\\HttpKernel\\HttpKernel::registerBundles`, - which must return an array of all bundles needed to - run the application; +* :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerBundles`, + which must return an array of all bundles needed to run the + application; * :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`, which loads the application configuration. @@ -115,10 +116,10 @@ Again, the Symfony2 Standard Edition provides an `AppKernel`_ in uses the name of the environment, which is passed to the Kernel's :method:`constructor` and is available via -:method:`getEnvironment()`, -to decide which bundles to create in ``registerBundles()``. This method -is meant to be extended by you when you start adding bundles to your -application. +:method:`Symfony\\Component\\HttpKernel\\Kernel::getEnvironment`, +to decide which bundles to create. The logic for that is in +``registerBundles()``, a method meant to be extended by you when you +start adding bundles to your application. You are, of course, free to create your own, alternative or additional ``AppKernel`` variants. All you need is to adapt your (or add a new) front @@ -182,5 +183,4 @@ are, of course, free to implement this method differently if you need .. _decorate: http://en.wikipedia.org/wiki/Decorator_pattern .. _Debug Component: https://github.com/symfony/symfony/pull/7441 .. _RewriteRule shipped with the Standard Edition: https://github.com/symfony/symfony-standard/blob/master/web/.htaccess) -.. _base HTTPKernel: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernel.php .. _template methods: http://en.wikipedia.org/wiki/Template_method_pattern From 7f3a4b04f05f3869aea9b50ca3e68bf75dc4d92c Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Sat, 6 Apr 2013 11:16:46 +0200 Subject: [PATCH 6/7] Not mention the Debug Component until it's ready --- cookbook/configuration/front_controllers_and_kernel.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst index 2ed3011a2fd..f712fc5d177 100644 --- a/cookbook/configuration/front_controllers_and_kernel.rst +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -49,7 +49,6 @@ to *`decorate`_* the kernel with additional features. Examples include: * Configure the autoloader or add additional autoloading mechanisms * Add HTTP level caching by wrapping the kernel with an instance of :doc:`AppCache` -* Enabling the `Debug component`_ When using Apache and the `RewriteRule shipped with the Standard Edition`_, the front controller can be chosen by requesting @@ -181,6 +180,5 @@ are, of course, free to implement this method differently if you need .. _app/console: https://github.com/symfony/symfony-standard/blob/master/app/console .. _AppKernel: https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php .. _decorate: http://en.wikipedia.org/wiki/Decorator_pattern -.. _Debug Component: https://github.com/symfony/symfony/pull/7441 .. _RewriteRule shipped with the Standard Edition: https://github.com/symfony/symfony-standard/blob/master/web/.htaccess) .. _template methods: http://en.wikipedia.org/wiki/Template_method_pattern From cc277e2e1852979dffa1c12bed6527b4279efcdf Mon Sep 17 00:00:00 2001 From: Matthias Pigulla Date: Sun, 7 Apr 2013 22:15:26 +0200 Subject: [PATCH 7/7] Mentioning the Debug component again as it has just been merged into master. --- cookbook/configuration/front_controllers_and_kernel.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst index f712fc5d177..2ed3011a2fd 100644 --- a/cookbook/configuration/front_controllers_and_kernel.rst +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -49,6 +49,7 @@ to *`decorate`_* the kernel with additional features. Examples include: * Configure the autoloader or add additional autoloading mechanisms * Add HTTP level caching by wrapping the kernel with an instance of :doc:`AppCache` +* Enabling the `Debug component`_ When using Apache and the `RewriteRule shipped with the Standard Edition`_, the front controller can be chosen by requesting @@ -180,5 +181,6 @@ are, of course, free to implement this method differently if you need .. _app/console: https://github.com/symfony/symfony-standard/blob/master/app/console .. _AppKernel: https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php .. _decorate: http://en.wikipedia.org/wiki/Decorator_pattern +.. _Debug Component: https://github.com/symfony/symfony/pull/7441 .. _RewriteRule shipped with the Standard Edition: https://github.com/symfony/symfony-standard/blob/master/web/.htaccess) .. _template methods: http://en.wikipedia.org/wiki/Template_method_pattern