From 4982029483b476a23455bdb6b4071e648129f674 Mon Sep 17 00:00:00 2001
From: John Bafford <john@bafford.com>
Date: Sun, 2 Jun 2013 22:25:46 -0400
Subject: [PATCH 1/4] Reorganize and expand quickstart big picture docs on
environments
* Add Environments section under "Understanding the Fundamentals" to introduce environments. This uses the glossary definition as a starting point and expands on it a little.
* Move the Web Profiler discussion out of Working with Environments into a separate section, and add a paragraph briefly summarizing what the profiler can do.
* Improve the Working with Environments section.
---
quick_tour/the_big_picture.rst | 124 +++++++++++++++++++++------------
1 file changed, 80 insertions(+), 44 deletions(-)
diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
index c6682938fc5..f5daaa20bfb 100644
--- a/quick_tour/the_big_picture.rst
+++ b/quick_tour/the_big_picture.rst
@@ -372,46 +372,75 @@ blog, a forum, ...) and which can be easily shared with other developers. As
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.
+Thee same application can be run using different configuration 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.
+
+Enivonments 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
+
+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.
-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:
+Symfony2 comes with two front controllers: ``app_dev.php`` provides the ``dev``
+environment, and ``app.php`` provides the ``prod`` environment. (The ``test``
+environment is normally only used when running unit tests, and so doesn't have
+a front controller.) All web accesses to Symfony2 normally go through one
+of these front controllers.
+
+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 +451,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<environment>` 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
--------------
From d617a99dfa277a9bb52721f613cce9c0f3053415 Mon Sep 17 00:00:00 2001
From: John Bafford <john@bafford.com>
Date: Mon, 3 Jun 2013 07:35:34 -0400
Subject: [PATCH 2/4] Minor formatting fixes
---
quick_tour/the_big_picture.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
index f5daaa20bfb..781b1db3860 100644
--- a/quick_tour/the_big_picture.rst
+++ b/quick_tour/the_big_picture.rst
@@ -377,15 +377,15 @@ Environments
Every Symfony application runs within an :term:`environment`. An environment
is a specific set of configuration and loaded bundles, represented by a string.
-Thee same application can be run using different configuration by running the
+The same application can be run using different configuration 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.
+defined — ``dev``, ``test`` and ``prod`` — but you can create your own as well.
Enivonments 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.
+Symfony2 comes with the `WebProfilerBundle` (described below), enabled only
+in the ``dev`` and ``test`` environments.
.. _quick-tour-big-picture-environments:
@@ -393,7 +393,7 @@ Working with Environments
-------------------------
Symfony2 loads configuration based on the name of the environment. Typically,
-you put your common configuration in ``config.yml``, and override where necessary
+you put your common configuration in ``config.yml`` and override where necessary
in the configuration for each environment. For example:
.. code-block:: yaml
@@ -422,7 +422,7 @@ environment is normally only used when running unit tests, and so doesn't have
a front controller.) All web accesses to Symfony2 normally go through one
of these front controllers.
-The ``AcmeDemoBundle`` is normally only available in the dev environment, but
+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:
From bee48530065f855c3ce278d5494675dbf67518ab Mon Sep 17 00:00:00 2001
From: John Bafford <john@bafford.com>
Date: Mon, 3 Jun 2013 11:39:08 -0400
Subject: [PATCH 3/4] Environments formatting and language tweaks
Also remove backticks on AcmeDemoBundle in Bundles section per PR comments.
---
quick_tour/the_big_picture.rst | 19 ++++++++++---------
1 file changed, 10 insertions(+), 9 deletions(-)
diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
index 781b1db3860..f4afe7db3eb 100644
--- a/quick_tour/the_big_picture.rst
+++ b/quick_tour/the_big_picture.rst
@@ -369,7 +369,7 @@ 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
@@ -381,10 +381,10 @@ The same application can be run using different configuration 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.
-Enivonments are useful by allowing a single application to have a dev environment
+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
+Symfony2 comes with the WebProfilerBundle (described below), enabled only
in the ``dev`` and ``test`` environments.
.. _quick-tour-big-picture-environments:
@@ -416,13 +416,14 @@ 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 front controllers: ``app_dev.php`` provides the ``dev``
-environment, and ``app.php`` provides the ``prod`` environment. (The ``test``
-environment is normally only used when running unit tests, and so doesn't have
-a front controller.) All web accesses to Symfony2 normally go through one
-of these front controllers.
+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
+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:
From e86e7c04e32cf3a7c35ac0536ea6247ffa1f72ca Mon Sep 17 00:00:00 2001
From: John Bafford <john@bafford.com>
Date: Mon, 3 Jun 2013 11:41:43 -0400
Subject: [PATCH 4/4] Grammar fix
---
quick_tour/the_big_picture.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
index f4afe7db3eb..38473e7084b 100644
--- a/quick_tour/the_big_picture.rst
+++ b/quick_tour/the_big_picture.rst
@@ -377,7 +377,7 @@ 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 using different configuration by running the
+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.