Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Add a section on front controllers and the AppKernel #2465

Closed
wants to merge 7 commits into from

5 participants

@mpdude
Q A
Doc fix? no
New docs? yes
Applies to all
Fixed tickets n/a

Here are some additions on how front controllers and custom AppKernels can be used to further tweak the runtime environment.

This is my first piece of .rst, so probably a lot of things and markup needs to be fixed. Additionally, we should discuss which is the best place for this document.

@WouterJ
Collaborator

Could you please add the pull request format to your PR message?

And I think this issue is related: #997

@WouterJ WouterJ commented on the diff
cookbook/configuration/front_controllers_and_kernel.rst
@@ -0,0 +1,99 @@
+Understanding how Front Controller, Kernel and Environments work together
@WouterJ Collaborator
WouterJ added a note

you are missing an .. index:: block at the first line of your page

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
@@ -0,0 +1,99 @@
+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
@WouterJ Collaborator
WouterJ added a note

you should break the line after the first character that crosses the 72th character (you should fix this in this hole diff)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
@@ -0,0 +1,99 @@
+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:
+
+* The front controller
+* The Kernel class
@WouterJ Collaborator
WouterJ added a note

put classnames inside literals (double backticks).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((2 lines not shown))
+=========================================================================
+
+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:
+
+* The front controller
+* The Kernel class
+* The environment
+
+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
@WouterJ Collaborator
WouterJ added a note

this is wrong. That's a markdown format. A Rst link format is:

The `front controller`_ is a well-known ...

at the bottom of the page:

 .. _`front controller`: http://en.wikipedia.org/wiki/Front_Controller_pattern
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((19 lines not shown))
+
+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
+``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*](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 :doc:`AppCache</book/http_cache#symfony2-reverse-proxy>`
+* Enabling the [Debug component](https://github.com/symfony/symfony/pull/7441)
@WouterJ Collaborator
WouterJ added a note

do not refer to unstable components/features in the stable documentation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((25 lines not shown))
+``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*](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 :doc:`AppCache</book/http_cache#symfony2-reverse-proxy>`
+* Enabling the [Debug component](https://github.com/symfony/symfony/pull/7441)
+
+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/...
@WouterJ Collaborator
WouterJ added a note

this should be:

the front controller can be chosen by requesting URLs like:

.. code-block:: text

    http://localhost/app_dev.php/some/path
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((38 lines not shown))
+.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/...
+
+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
@WouterJ Collaborator
WouterJ added a note
The ``AppKernel``
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((44 lines not shown))
+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.
@WouterJ Collaborator
WouterJ added a note

please use api links here (:method: role)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((49 lines not shown))
+.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:
@WouterJ Collaborator
WouterJ added a note

should be an api link aswell (:class: role)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((51 lines not shown))
+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:
+
+* :method:`registerBundles()<Symfony\\Component\\HttpKernel\\HttpKernel::registerBundles>`, which must return an array of all bundles needed to
@WouterJ Collaborator
WouterJ added a note

the :method: role automatically uses the registerBundles() name, you should only use the part between < and >

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((73 lines not shown))
+
+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<Symfony\\Component\\HttpKernel\\Kernel::__construct>` and is available via :method:`getEnvironment()<Symfony\\Component\\HttpKernel\\Kernel::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
+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
@WouterJ Collaborator
WouterJ added a note

the lines should get indented with 3 spaces, otherwise they don't belong to the list item

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((72 lines not shown))
+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<Symfony\\Component\\HttpKernel\\Kernel::__construct>` and is available via :method:`getEnvironment()<Symfony\\Component\\HttpKernel\\Kernel::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
+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
@WouterJ Collaborator
WouterJ added a note

an api link aswell

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((82 lines not shown))
+``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
+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.
+
+The environments
+================
+
+Environments have been covered extensively :doc:`in the previous chapter</cookbook/configuration/environments>`. 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()<Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration>` method is used for.
@WouterJ Collaborator
WouterJ added a note
[...] the ``Kernel`` is supposed [...]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((92 lines not shown))
+steps which the
+:class:`base HttpKernel <Symfony\\Component\\HttpKernel\\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
@mpdude
mpdude added a note

@WouterJ Is that correct with a triple ` plus the underscore?

@WouterJ Collaborator
WouterJ added a note

@mpdude no, you can't mix inline formats in Sphinx. So you just need to use 1 backtick to create a link.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mpdude

@WouterJ Thanks for the quick feedback and sorry for getting so many basics wrong.

I hope I did not forget one of your comments.

@mpdude

@lsmith77 as you opened #997 it would be nice to get your feedback as well

cookbook/configuration/front_controllers_and_kernel.rst
((27 lines not shown))
+
+
+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.
+
+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 reques and
@lsmith77
lsmith77 added a note

typo reques missing a t

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((114 lines not shown))
+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
+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
+ :method:`Symfony\\Component\\HttpKernel\\HttpKernel::registerBundles`
+ method or
+* add more sophisticated ways of loading the application's configuration
+ from a different set of files.
+
@lsmith77
lsmith77 added a note

enabling different front controllers on different servers in order to deploy or scale specifically functionality independently (f.e. admin UI, frontend UI, database migrations, REST API)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((106 lines not shown))
+
+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<Symfony\\Component\\HttpKernel\\Kernel::__construct>`
+and is available via
+:method:`getEnvironment()<Symfony\\Component\\HttpKernel\\Kernel::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
+controller to make use of the new kernel. Adding additional kernel
+implementations might be useful to
@lsmith77
lsmith77 added a note

Note the name and location of the AppKernel is not fixed. When putting multiple Kernel's into a single application it might therefore make sense to add additional sub-directories. For example app/admin/AdminKernel.php, app/api/ApiKernel.php etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@lsmith77

there are several places that talk about Apache rewrite rules, i think it should be stated somewhere that equivalent behavior can be achieved with pretty much every other web server.

@mpdude

All feedback picked up - thanks!

cookbook/configuration/front_controllers_and_kernel.rst
((19 lines not shown))
+.. 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`_ is a well-known design pattern; it is a
+section of
+code that *all* requests served by an application run through.
@stof
stof added a note

The way it is wrapped is weird here

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((83 lines not shown))
+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
+: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 <Symfony\\Component\\HttpKernel\\HttpKernel>`
@stof
stof added a note

This is wrong. You are confusing HttpKernel and Kernel

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((86 lines not shown))
+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
+: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 <Symfony\\Component\\HttpKernel\\HttpKernel>`
+does not implement:
+
+* :method:`Symfony\\Component\\HttpKernel\\HttpKernel::registerBundles`,
@stof
stof added a note

This method does not exist. It is the wrong class

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((103 lines not shown))
+ 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<Symfony\\Component\\HttpKernel\\Kernel::__construct>`
+and is available via
+:method:`getEnvironment()<Symfony\\Component\\HttpKernel\\Kernel::getEnvironment>`,
@stof
stof added a note

This can be simplified as :method:`Symfony\\Component\\HttpKernel\\Kernel::getEnvironment`

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((104 lines not shown))
+
+* :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<Symfony\\Component\\HttpKernel\\Kernel::__construct>`
+and is available via
+:method:`getEnvironment()<Symfony\\Component\\HttpKernel\\Kernel::getEnvironment>`,
+to decide which bundles to create in ``registerBundles()``. This method
@stof
stof added a note

Does this method refer to getEnvironment or registerbundles here ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@stof stof commented on the diff
cookbook/configuration/front_controllers_and_kernel.rst
((168 lines not shown))
+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. 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
+.. _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
@stof
stof added a note

This link should be removed

@mpdude
mpdude added a note

I think that's an interesting feature and worth mentioning once it gets merged. How can we make sure it will be reflected then?

@stof
stof added a note

it should be documented only once the component is merged, and not with a link to the PR adding it but to the component documentation (which will need to be written first)

@mpdude
mpdude added a note

Yes, but how can we make sure now that we don't forget to add it here once it becomes ready?

@WouterJ Collaborator
WouterJ added a note

@mpdude I've put it on my doc watch list, as soon as we have documentation, I create a PR adding it.

@stof
stof added a note

Thus, keeping this unused link here would not ensure we don't forget it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
cookbook/configuration/front_controllers_and_kernel.rst
((170 lines not shown))
+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
+.. _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
@stof
stof added a note

This link should be removed as it is unused

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mpdude

@wouterj thanks for keeping an eye on it. I removed the reference to the Debug Component.

@mpdude

symfony/symfony#7441 has been merged.

@WouterJ
Collaborator

@mpdude yes, I saw it. You can add that component in the list now. When #2479 is merged into the docs, you can add a link to that documentation as well.

@mpdude

@wouterj I think I am done with it for the moment, feel free to merge it at any time.

If you do so before #2479, I'll ask over there to update the link to it on this page.

@weaverryan weaverryan referenced this pull request from a commit
@weaverryan weaverryan [#2465] Fixing tiny typo f1e3ca9
@weaverryan
Collaborator

Hi Matthias!

Very nice work! I've patched this into the 2.0 branch so that all branches can enjoy it, and removed the Debug reference (but re-added it to the master branch only).

Thanks!

@weaverryan weaverryan closed this
@mpdude mpdude deleted the branch
@mpdude

@weaverryan just saw that the 'decorate' link in the Front Controller paragraph is broken. Could you please fix that?

Thanks!

@mpdude

The link to the RewriteRule is broken as well :-(

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
View
186 cookbook/configuration/front_controllers_and_kernel.rst
@@ -0,0 +1,186 @@
+.. index::
+ single: How front controller, ``AppKernel`` and environments
+ work together
+
+Understanding how Front Controller, Kernel and Environments work together
@WouterJ Collaborator
WouterJ added a note

you are missing an .. index:: block at the first line of your page

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+=========================================================================
+
+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. To hook into this process, you need to understand three
+parts that work together:
+
+* The front controller
+* 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`_ 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`_, 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
+:doc:`AppCache</book/http_cache#symfony2-reverse-proxy>`
+* Enabling the `Debug component`_
+
+When using Apache and the `RewriteRule shipped with the
+Standard Edition`_, the front controller can be chosen by requesting
+URLs like::
+
+.. code-block:: text
+
+ 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.
+
+.. note::
+
+ 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.
+
+.. 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,
+only that is not used for web, but for command line requests.
+
+The ``AppKernel``
+=================
+
+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 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\\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.
+
+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<Symfony\\Component\\HttpKernel\\Kernel::__construct>`
+and is available via
+: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
+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.
+
+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
+ </cookbook/configuration /override_dir_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</cookbook/configuration/environments>`,
+ 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 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. 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
+.. _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
@stof
stof added a note

This link should be removed

@mpdude
mpdude added a note

I think that's an interesting feature and worth mentioning once it gets merged. How can we make sure it will be reflected then?

@stof
stof added a note

it should be documented only once the component is merged, and not with a link to the PR adding it but to the component documentation (which will need to be written first)

@mpdude
mpdude added a note

Yes, but how can we make sure now that we don't forget to add it here once it becomes ready?

@WouterJ Collaborator
WouterJ added a note

@mpdude I've put it on my doc watch list, as soon as we have documentation, I create a PR adding it.

@stof
stof added a note

Thus, keeping this unused link here would not ensure we don't forget it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+.. _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
View
1  cookbook/configuration/index.rst
@@ -5,6 +5,7 @@ Configuration
:maxdepth: 2
environments
+ front_controllers_and_kernel
override_dir_structure
external_parameters
pdo_session_storage
Something went wrong with that request. Please try again.