From 0cfbd3572a474291dc584e22577e6fc1b822a63c Mon Sep 17 00:00:00 2001 From: Richard Hoar Date: Sat, 5 Feb 2011 13:44:20 -0800 Subject: [PATCH 01/10] changing intro paragraph moved web server config tip with the web server setup --- quick_tour/the_big_picture.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index f1c0d685869..bcd2eac7132 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -1,10 +1,9 @@ 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 Symfony 2 in 10 minutes! This tutorial contains some of the +important concepts behind Symfony2. It explains how to get started fast with +Symfony2 by showing you the structure of a simple ready-made project. If you have ever used a web framework before, you should feel right at home with Symfony2. @@ -64,6 +63,15 @@ Now, request your first "real" Symfony2 webpage: 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 ------------------------------- @@ -301,12 +309,6 @@ 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 From c78e7dc252908f1b54ee0bb41c2b7a5c77207790 Mon Sep 17 00:00:00 2001 From: Cullen Walsh Date: Sat, 5 Feb 2011 13:55:40 -0800 Subject: [PATCH 02/10] Adjusting wording on The Big Picture intro --- 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 bcd2eac7132..85dd4d80d7d 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -1,11 +1,11 @@ The Big Picture =============== -Start using Symfony 2 in 10 minutes! This tutorial contains some of the -important concepts behind Symfony2. 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:: @@ -14,8 +14,8 @@ 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 From bbfff9fb99cd65855ff6bbfbed6cda8f316c3f14 Mon Sep 17 00:00:00 2001 From: Richard Hoar Date: Sat, 5 Feb 2011 14:15:17 -0800 Subject: [PATCH 03/10] updated Checking the Configuration --- quick_tour/the_big_picture.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 85dd4d80d7d..791b5e624ca 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -50,14 +50,15 @@ 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/ From 124d2a675572476581201ac50277d780de2eec39 Mon Sep 17 00:00:00 2001 From: Cullen Walsh Date: Sat, 5 Feb 2011 14:15:08 -0800 Subject: [PATCH 04/10] Adjusting wording for Downloading and Installing --- quick_tour/the_big_picture.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 791b5e624ca..30397f7045e 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -18,11 +18,10 @@ 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:: From 16f871bc67f5637d32c655b0103720866d801561 Mon Sep 17 00:00:00 2001 From: Richard Hoar Date: Sat, 5 Feb 2011 15:03:47 -0800 Subject: [PATCH 05/10] updated Configuration --- quick_tour/the_big_picture.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 30397f7045e..4307ace5a3b 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -101,19 +101,16 @@ Fabien!``). Configuration ~~~~~~~~~~~~~ -But how does Symfony2 route the request to your code? Simply by reading some -configuration file. +Symfony2 routes the request to your code by using a 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 +All Symfony2 configuration files can be written in PHP, XML or `YAML`_(YAML is +a simple format that makes the description of configuration settings straightforward). .. 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 From 9dc4f5c0fc0c36326f0ff7a8555f83c6800ac092 Mon Sep 17 00:00:00 2001 From: Cullen Walsh Date: Sat, 5 Feb 2011 14:48:13 -0800 Subject: [PATCH 06/10] rephrasing Creating your first Application --- quick_tour/the_big_picture.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 4307ace5a3b..bb169a9f986 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -75,9 +75,9 @@ Symfony2 should congratulate you for your hard work so far! 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 @@ -88,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 From c60bafc525f8d01fb461b39f86cb48425ef79cb1 Mon Sep 17 00:00:00 2001 From: Richard Hoar Date: Sat, 5 Feb 2011 16:10:11 -0800 Subject: [PATCH 07/10] updated Routing --- quick_tour/the_big_picture.rst | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index bb169a9f986..099e9afa23b 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -101,11 +101,9 @@ Fabien!``). Configuration ~~~~~~~~~~~~~ -Symfony2 routes the request to your code by using a configuration file. - -All Symfony2 configuration files can be written in 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:: @@ -119,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:: @@ -163,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:: @@ -203,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. From bd71819718defcc97f6f52c7908eba664f30daf3 Mon Sep 17 00:00:00 2001 From: Cullen Walsh Date: Sat, 5 Feb 2011 16:09:36 -0800 Subject: [PATCH 08/10] Better describing controllers --- quick_tour/the_big_picture.rst | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 099e9afa23b..68d0ae7e73f 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -218,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: @@ -243,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. @@ -267,6 +268,12 @@ 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 ~~~~~~~~~ From 42b6814c82bc287fb10f89a3ca310665f4dc1b3f Mon Sep 17 00:00:00 2001 From: Richard Hoar Date: Sat, 5 Feb 2011 16:41:44 -0800 Subject: [PATCH 09/10] updated Templates and Final Thoughts --- quick_tour/the_big_picture.rst | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 68d0ae7e73f..b4fb4c5f7fc 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -277,10 +277,9 @@ developers. In our example, we only have one bundle, ``HelloBundle``. 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 @@ -291,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 @@ -326,11 +321,10 @@ 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/ From fd9639ca53723ee3a349cca1ed2b552087fdaf7c Mon Sep 17 00:00:00 2001 From: Cullen Walsh Date: Sat, 5 Feb 2011 16:41:33 -0800 Subject: [PATCH 10/10] Improving Working with Environments --- quick_tour/the_big_picture.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index b4fb4c5f7fc..9d73d289c0d 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -297,13 +297,12 @@ traditional PHP templates if you choose. 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 @@ -314,9 +313,9 @@ And if you use Apache with ``mod_rewrite`` enabled, you can even omit the 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 --------------