Skip to content

Reorganize and expand quickstart big picture docs on environments #2683

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Reorganize and expand quickstart big picture docs on environments #2683

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4982029
Reorganize and expand quickstart big picture docs on environments
jbafford Jun 3, 2013
d617a99
Minor formatting fixes
jbafford Jun 3, 2013
bee4853
Environments formatting and language tweaks
jbafford Jun 3, 2013
e86e7c0
Grammar fix
jbafford Jun 3, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 82 additions & 45 deletions quick_tour/the_big_picture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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<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
--------------
Expand Down