diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index f1c0d685869..9d73d289c0d 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -1,12 +1,11 @@ The Big Picture =============== -So, you want to try out Symfony2 but only have 10 minutes or so? This first -part of this tutorial has been written for you. It explains how to get started -fast with Symfony2 by showing you the structure of a simple ready-made -project. +Start using Symfony2 in 10 minutes! This tutorial contains some important +concepts behind Symfony2. It explains how to get started quickly by showing you +the structure of a sample project. -If you have ever used a web framework before, you should feel right at home +If you have used a web framework before, you should feel right at home with Symfony2. .. index:: @@ -15,15 +14,14 @@ with Symfony2. Downloading and Installing Symfony2 ----------------------------------- -First, check that you have at least PHP 5.3.2 installed and correctly -configured to work with a web server like Apache. +First, check that you have installed and configured a webserver (such as +Apache) with PHP 5.3.2 or higher. Ready? Let's start by downloading Symfony2. To get started even faster, we are -going to use the "Symfony2 sandbox". It is a Symfony2 project where all the -required libraries and some simple controllers are already included; the basic -configuration is also already done. The great advantage of the sandbox over -other types of installation is that you can start experimenting with Symfony2 -immediately. +going to use the "Symfony2 sandbox". This is a preconfigured Symfony2 project +that includes some simple controllers and their required libraries. The great +advantage of the sandbox over other methods of installation is you can start +experimenting with Symfony2 immediately. Download the `sandbox`_, and unpack it in your root web directory. You should now have a ``sandbox/`` directory:: @@ -51,25 +49,35 @@ should now have a ``sandbox/`` directory:: Checking the Configuration -------------------------- -To avoid some headaches further down the line, check that your configuration -can run a Symfony2 project smoothly by requesting the following URL: +Symfony2 comes with a visual server configuration tester to help avoid some +headaches that come from web server or php misconfiguration. Please use +the following url to see the diagnostics for your server: http://localhost/sandbox/web/check.php -Read the script output carefully and fix any problem that it finds. +Read the script output carefully and correct any oustanding issues. -Now, request your first "real" Symfony2 webpage: +Now you can request your first "real" Symfony2 webpage: http://localhost/sandbox/web/app_dev.php/ Symfony2 should congratulate you for your hard work so far! +.. tip:: + + On production servers, you should point your web root directory to the + ``web/`` directory to secure your installation and have an even better + looking URL: + + http://localhost/hello/Fabien + + Creating your first Application ------------------------------- -The sandbox comes with a simple Hello World ":term:`application`" and that's -the application we will use to learn more about Symfony2. Go to the following -URL to be greeted by Symfony2 (replace Fabien with your first name): +The sandbox comes with a simple Hello World ":term:`application`" we will use +to learn more about Symfony2. Go to the following URL to be greeted by Symfony2 +(replace Fabien with your first name): http://localhost/sandbox/web/app_dev.php/hello/Fabien @@ -80,7 +88,7 @@ What's going on here? Let's dissect the URL: * ``app_dev.php``: This is a "front controller". It is the unique entry point of the application and it responds to all user requests; -* ``/hello/Fabien``: This is the "virtual" path to the resource the user wants +* ``/hello/Fabien``: This is the virtual path to the resource the user wants to access. Your responsibility as a developer is to write the code that maps the user @@ -93,19 +101,14 @@ Fabien!``). Configuration ~~~~~~~~~~~~~ -But how does Symfony2 route the request to your code? Simply by reading some -configuration file. - -All Symfony2 configuration files can be written in either PHP, XML, or `YAML`_ -(YAML is a simple format that makes the description of configuration settings -straightforward). +Symfony2 configuration files can be written in PHP, XML or `YAML`_. The +different types are compatible and may be used interchangeably within an +application. .. tip:: The sandbox defaults to YAML, but you can easily switch to XML or PHP by - editing the ``app/AppKernel.php`` file. You can switch now by looking at - the bottom of this file for instructions (the tutorials show the - configuration for all supported formats). + editing the ``app/AppKernel.php`` file. .. index:: single: Routing @@ -114,7 +117,8 @@ straightforward). Routing ~~~~~~~ -So, Symfony2 routes the request by reading the routing configuration file: +Symfony2 routes the request to your code by using a configuration file. Here +are a few examples of the routing configuration file for our application: .. configuration-block:: @@ -158,9 +162,14 @@ So, Symfony2 routes the request by reading the routing configuration file: return $collection; -The first few lines of the routing configuration file define the code called -when the user requests the "``/``" resource. More interesting is the last -part, which imports another routing configuration file that reads as follows: +The first few lines of the routing configuration file define the code that is +executed when the user requests the "``/``" resource. + +.. tip:: + + If you're comfortable with routing, have a look at the last directive of + the configuration file. Symfony2 can include routing information from + other bundles. .. configuration-block:: @@ -198,7 +207,7 @@ part, which imports another routing configuration file that reads as follows: return $collection; -Here we go! As you can see, the "``/hello/{name}``" resource pattern (a string +As you can see, the "``/hello/{name}``" resource pattern (a string enclosed in curly brackets like ``{name}`` is a placeholder) is mapped to a controller, referenced by the ``_controller`` value. @@ -209,8 +218,8 @@ controller, referenced by the ``_controller`` value. Controllers ~~~~~~~~~~~ -The controller is responsible for returning a representation of the resource -(most of the time an HTML one) and it is defined as a PHP class: +The controller defines actions to handle users requests and prepares responses +(often in HTML). .. code-block:: php :linenos: @@ -234,21 +243,22 @@ The controller is responsible for returning a representation of the resource The code is pretty straightforward but let's explain it line by line: -* *line 3*: Symfony2 takes advantage of new PHP 5.3 features and as such, all - controllers are properly namespaced (the namespace is the first part of the - ``_controller`` routing value: ``HelloBundle``). +* *line 3*: Symfony2 takes advantage of new PHP 5.3 namespacing features, and + all controllers should be properly namespaced. Per the routing file above, + the namespace is the first part of the ``_controller`` routing value: + ``HelloBundle``). -* *line 7*: The controller name is the concatenation of the second part of the - ``_controller`` routing value (``Hello``) and ``Controller``. It extends the - built-in ``Controller`` class, which provides useful shortcuts (as we will - see later in this tutorial). +* *line 7*: The controller name is the combination of the second part of the + ``_controller`` routing value (``Hello``) and the word ``Controller``. It + extends the built-in ``Controller`` class, which provides useful shortcuts + (as we will see later in this tutorial). -* *line 9*: Each controller is made of several actions. As per the +* *line 9*: Each controller is made of several actions. As per the routing configuration, the hello page is handled by the ``index`` action (the third part of the ``_controller`` routing value). This method receives the - resource placeholder values as arguments (``$name`` in our case). + placeholder values as arguments (``$name`` in our case). -* *line 11*: The ``render()`` method loads and renders a template +* *line 11*: The ``render()`` method loads and renders a template file (``HelloBundle:Hello:index.html.twig``) with the variables passed as a second argument. @@ -258,13 +268,18 @@ organized in bundles. In Symfony2 speak, a bundle is a structured set of files feature (a blog, a forum, ...) and which can be easily shared with other developers. In our example, we only have one bundle, ``HelloBundle``. +.. tip:: + + In general, controller actions should be as short as possible. If one is + getting too long, consider refactoring some of the more complicated code to + the service layer (which will be discussed later). + Templates ~~~~~~~~~ -So, the controller renders the ``HelloBundle:Hello:index.html.twig`` template. -But what's in a template name? ``HelloBundle`` is the bundle name, ``Hello`` -is the controller, and ``index.html.twig`` the template name. By default, the -sandbox uses Twig as its template engine: +The controller renders the ``HelloBundle:Hello:index.html.twig`` template. By +default, the sandbox uses Twig as its template engine but you can also use +traditional PHP templates if you choose. .. code-block:: jinja @@ -275,10 +290,6 @@ sandbox uses Twig as its template engine: Hello {{ name }}! {% endblock %} -Congratulations! You have looked at your first Symfony2 piece of code. That was -not so hard, was it? Symfony2 makes it really easy to implement web sites -better and faster. - .. index:: single: Environment single: Configuration; Environment @@ -286,13 +297,12 @@ better and faster. Working with Environments ------------------------- -Now that you have a better understanding on how Symfony2 works, have a closer +Now that you have a better understanding of how Symfony2 works, have a closer look at the bottom of the page; you will notice a small bar with the Symfony2 -and PHP logos. It is called the "Web Debug Toolbar" and it is the developer's +and PHP logos. This is called the "Web Debug Toolbar" and it is the developer's best friend. Of course, such a tool must not be displayed when you deploy your -application to your production servers. That's why you will find another front -controller in the ``web/`` directory (``app.php``), optimized for the -production environment: +application to production. That's why you will find another front controller in +the ``web/`` directory (``app.php``), optimized for the production environment: http://localhost/sandbox/web/app.php/hello/Fabien @@ -301,26 +311,19 @@ And if you use Apache with ``mod_rewrite`` enabled, you can even omit the http://localhost/sandbox/web/hello/Fabien -Last but not least, on the production servers, you should point your web root -directory to the ``web/`` directory to secure your installation and have an even -better looking URL: - - http://localhost/hello/Fabien - To make the production environment as fast as possible, Symfony2 maintains a cache under the ``app/cache/`` directory. When you make changes to the code or -configuration, you need to manually remove the cached files. That's why you -should always use the development front controller (``app_dev.php``) when -working on a project. +configuration, you need to manually remove the cached files. The development +front controller (``app_dev.php``) does not use this cache and your changes +appear immediately, thus is recommended when working on a project. Final Thoughts -------------- -The 10 minutes are over. By now, you should be able to create your own simple -routes, controllers, and templates. As an exercise, try to build something -more useful than the Hello application! But if you are eager to learn more -about Symfony2, you can read the next part of this tutorial right away, where -we dive more into the templating system. +Thanks for trying out Symfony2! By now, you should be able to create your own +simple routes, controllers and templates. As an exercise, try to build +something more useful than the Hello application! If you are eager to +learn more about Symfony2, dive into the next section: the view system. .. _sandbox: http://symfony-reloaded.org/code#sandbox .. _YAML: http://www.yaml.org/