diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index c6682938fc5..38473e7084b 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -369,49 +369,79 @@ have seen so far. All the code you write for your application is organized in bundles. In Symfony2 speak, a bundle is a structured set of files (PHP files, stylesheets, JavaScripts, images, ...) that implements a single feature (a blog, a forum, ...) and which can be easily shared with other developers. As -of now, you have manipulated one bundle, ``AcmeDemoBundle``. You will learn +of now, you have manipulated one bundle, AcmeDemoBundle. You will learn more about bundles in the last chapter of this tutorial. +Environments +~~~~~~~~~~~~ + +Every Symfony application runs within an :term:`environment`. An environment +is a specific set of configuration and loaded bundles, represented by a string. +The same application can be run with different configurations by running the +application in different environments. Symfony2 comes with three environments +defined — ``dev``, ``test`` and ``prod`` — but you can create your own as well. + +Environments are useful by allowing a single application to have a dev environment +built for debugging and a production environment optimized for speed. You might +also load specific bundles based on the selected environment. For example, +Symfony2 comes with the WebProfilerBundle (described below), enabled only +in the ``dev`` and ``test`` environments. + .. _quick-tour-big-picture-environments: Working with Environments ------------------------- -Now that you have a better understanding of how Symfony2 works, take a closer -look at the bottom of any Symfony2 rendered page. You should notice a small -bar with the Symfony2 logo. This is called the "Web Debug Toolbar" and it -is the developer's best friend. +Symfony2 loads configuration based on the name of the environment. Typically, +you put your common configuration in ``config.yml`` and override where necessary +in the configuration for each environment. For example: -.. image:: /images/quick_tour/web_debug_toolbar.png - :align: center +.. code-block:: yaml -But what you see initially is only the tip of the iceberg; click on the long -hexadecimal number (the session token) to reveal yet another very useful -Symfony2 debugging tool: the profiler. + # app/config/config_dev.yml + imports: + - { resource: config.yml } -.. image:: /images/quick_tour/profiler.png - :align: center + web_profiler: + toolbar: true + intercept_redirects: false -Of course, you won't want to show these tools when you deploy your application -to production. That's why you will find another front controller in the -``web/`` directory (``app.php``), which is optimized for the production environment. -The ``AcmeDemoBundle`` is normally only available in the dev environment (see -the note below), but if you were to add it to the production environment, you -could go here: +In this example, the ``dev`` environment loads the ``config_dev.yml`` configuration +file, which itself imports the global ``config.yml`` file and then modifies it by +enabling the web debug toolbar. + +To make your application respond faster, Symfony2 maintains a cache under the +``app/cache/`` directory. In the ``dev`` environment, this cache is flushed +automatically whenever you make changes to any code or configuration. But that's +not the case in the ``prod`` environment, where performance is key. That's why you +should always use the development environment when developing your application. + +Symfony2 comes with two web-accessible front controllers: ``app_dev.php`` +provides the ``dev`` environment, and ``app.php`` provides the ``prod`` environment. +All web accesses to Symfony2 normally go through one of these front controllers. +(The ``test`` environment is normally only used when running unit tests, and so +doesn't have a dedicated front controller. The console tool also provides a +front controller that can be used with any environment.) + +The AcmeDemoBundle is normally only available in the dev environment, but +if you were to add it (and its routes) to the production environment, you could +go here: .. code-block:: text http://localhost/Symfony/web/app.php/demo/hello/Fabien -And if you use Apache with ``mod_rewrite`` enabled, you can even omit the -``app.php`` part of the URL: +If instead of using php's built-in webserver, you use Apache with ``mod_rewrite`` +enabled and take advantage of the ``.htaccess`` file Symfony2 provides +in ``web/``, you can even omit the ``app.php`` part of the URL. The default +``.htaccess`` points all requests to the ``app.php`` front controller: .. code-block:: text http://localhost/Symfony/web/demo/hello/Fabien -Last but not least, on production servers, you should point your web root -directory to the ``web/`` directory to secure your installation and have an +Finally, on production servers, you should point your web root directory +to the ``web/`` directory to better secure your installation and have an even better looking URL: .. code-block:: text @@ -422,35 +452,42 @@ even better looking URL: Note that the three URLs above are provided here only as **examples** of how a URL looks like when the production front controller is used (with or - without mod_rewrite). If you actually try them in an out of the box - installation of *Symfony Standard Edition* you will get a 404 error as - *AcmeDemoBundle* is enabled only in dev environment and its routes imported - in *app/config/routing_dev.yml*. + without mod_rewrite). If you actually try them in an out-of-the-box + installation of *Symfony Standard Edition*, you will get a 404 error since + *AcmeDemoBundle* is enabled only in the dev environment and its routes imported + from *app/config/routing_dev.yml*. -To make your application respond faster, Symfony2 maintains a cache under the -``app/cache/`` directory. In the development environment (``app_dev.php``), -this cache is flushed automatically whenever you make changes to any code or -configuration. But that's not the case in the production environment -(``app.php``) where performance is key. That's why you should always use -the development environment when developing your application. +.. _quick-tour-big-picture-web-debug-toolbar: -Different :term:`environments` of a given application differ -only in their configuration. In fact, a configuration can inherit from another -one: +The Web Debug Toolbar and Profiler +---------------------------------- -.. code-block:: yaml - # app/config/config_dev.yml - imports: - - { resource: config.yml } +Now that you have a better understanding of how Symfony2 works, take a closer +look at the bottom of any Symfony2 rendered page. You should notice a small +bar with the Symfony2 logo. This is the "Web Debug Toolbar", and it is a +Symfony2 developer's best friend. - web_profiler: - toolbar: true - intercept_redirects: false +.. image:: /images/quick_tour/web_debug_toolbar.png + :align: center + +What you see initially is only the tip of the iceberg; click on the long +hexadecimal number (the session token) to reveal yet another very useful +Symfony2 debugging tool: the profiler. + +.. image:: /images/quick_tour/profiler.png + :align: center + +When enabled (by default in the dev and test environments), the Profiler +records a great deal of information on each request made to your application. +It allows you to view details of each request, including, but not limited to, +GET or POST parameters and the request headers; logs; an execution timeline; +information on the currently logged in user; Doctrine queries; and more. + +Of course, it would be unwise to have these tools enabled when you deploy +your application, so by default, the profiler is not enabled in the ``prod`` +environment. (In fact, its bundle is not even loaded). -The ``dev`` environment (which loads the ``config_dev.yml`` configuration file) -imports the global ``config.yml`` file and then modifies it by, in this example, -enabling the web debug toolbar. Final Thoughts --------------