diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst index 2a499195cf1..2dd2ebd4922 100644 --- a/quick_tour/the_architecture.rst +++ b/quick_tour/the_architecture.rst @@ -1,11 +1,11 @@ The Architecture ================ -You are my hero! Who would have thought that you would still be here after the -first three parts? Your efforts will be well rewarded soon. The first three -parts didn't look too deeply at the architecture of the framework. Because it -makes Symfony stand apart from the framework crowd, let's dive into the -architecture now. +You are my hero! Who would have thought that you would still be here after +the first three parts? Your efforts will be well rewarded soon. The first +three parts didn't look too deeply at the architecture of the framework. +Because it makes Symfony stand apart from the framework crowd, let's dive +into the architecture now. Understanding the Directory Structure ------------------------------------- @@ -26,7 +26,7 @@ The ``web/`` Directory ~~~~~~~~~~~~~~~~~~~~~~ The web root directory is the home of all public and static files like images, -stylesheets, and JavaScript files. It is also where each :term:`front controller` +stylesheets and JavaScript files. It is also where each :term:`front controller` lives, such as the production controller shown here:: // web/app.php @@ -57,8 +57,8 @@ configuration and as such, it is stored in the ``app/`` directory. This class must implement two methods: ``registerBundles()`` - Must return an array of all bundles needed to run the application, as explained - in the next section. + Must return an array of all bundles needed to run the application, as + explained in the next section. ``registerContainerConfiguration()`` Loads the application configuration (more on this later). @@ -74,24 +74,25 @@ Understanding the Bundle System This section introduces one of the greatest and most powerful features of Symfony, the :term:`bundle` system. -A bundle is kind of like a plugin in other software. So why is it called a -*bundle* and not a *plugin*? This is because *everything* is a bundle in -Symfony, from the core framework features to the code you write for your -application. +A bundle is kind of like a plugin in other software. So why is it +called a *bundle* and not a *plugin*? This is because *everything* is a +bundle in Symfony, from the core framework features to the code you write +for your application. -All the code you write for your application is organized in bundles. In Symfony -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. +All the code you write for your application is organized in bundles. In +Symfony 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. Bundles are first-class citizens in Symfony. This gives you the flexibility -to use pre-built features packaged in third-party bundles or to distribute your -own bundles. It makes it easy to pick and choose which features to enable in -your application and optimize them the way you want. And at the end of the day, -your application code is just as *important* as the core framework itself. - -Symfony already includes an AppBundle that you may use to start developing your -application. Then, if you need to split the application into reusable +to use pre-built features packaged in third-party bundles or to distribute +your own bundles. It makes it easy to pick and choose which features to +enable in your application and optimize them the way you want. And at the +end of the day, your application code is just as *important* as the core +framework itself. + +Symfony already includes an AppBundle that you may use to start developing +your application. Then, if you need to split the application into reusable components, you can create your own bundles. Registering a Bundle @@ -125,15 +126,15 @@ a single Bundle class that describes it:: return $bundles; } -In addition to the AppBundle that was already talked about, notice that the -kernel also enables other bundles that are part of Symfony, such as FrameworkBundle, -DoctrineBundle, SwiftmailerBundle and AsseticBundle. +In addition to the AppBundle that was already talked about, notice that +the kernel also enables other bundles that are part of Symfony, such as +FrameworkBundle, DoctrineBundle, SwiftmailerBundle and AsseticBundle. Configuring a Bundle ~~~~~~~~~~~~~~~~~~~~ -Each bundle can be customized via configuration files written in YAML, XML, or -PHP. Have a look at this sample of the default Symfony configuration: +Each bundle can be customized via configuration files written in YAML, XML, +or PHP. Have a look at this sample of the default Symfony configuration: .. code-block:: yaml @@ -173,14 +174,15 @@ PHP. Have a look at this sample of the default Symfony configuration: # ... -Each first level entry like ``framework``, ``twig`` and ``swiftmailer`` defines -the configuration for a specific bundle. For example, ``framework`` configures -the FrameworkBundle while ``swiftmailer`` configures the SwiftmailerBundle. +Each first level entry like ``framework``, ``twig`` and ``swiftmailer`` +defines the configuration for a specific bundle. For example, ``framework`` +configures the FrameworkBundle while ``swiftmailer`` configures the +SwiftmailerBundle. -Each :term:`environment` can override the default configuration by providing a -specific configuration file. For example, the ``dev`` environment loads the -``config_dev.yml`` file, which loads the main configuration (i.e. ``config.yml``) -and then modifies it to add some debugging tools: +Each :term:`environment` can override the default configuration by providing +a specific configuration file. For example, the ``dev`` environment loads +the ``config_dev.yml`` file, which loads the main configuration (i.e. +``config.yml``) and then modifies it to add some debugging tools: .. code-block:: yaml @@ -202,8 +204,9 @@ Extending a Bundle ~~~~~~~~~~~~~~~~~~ In addition to being a nice way to organize and configure your code, a bundle -can extend another bundle. Bundle inheritance allows you to override any existing -bundle in order to customize its controllers, templates, or any of its files. +can extend another bundle. Bundle inheritance allows you to override any +existing bundle in order to customize its controllers, templates, or any +of its files. Logical File Names .................. @@ -226,13 +229,14 @@ For controllers, you need to reference actions using the format Extending Bundles ................. -If you follow these conventions, then you can use :doc:`bundle inheritance ` -to override files, controllers or templates. For example, you can create -a bundle - NewBundle - and specify that it overrides AppBundle. -When Symfony loads the ``AppBundle:Default:index`` controller, it will -first look for the ``DefaultController`` class in NewBundle and, if -it doesn't exist, then look inside AppBundle. This means that one bundle -can override almost any part of another bundle! +If you follow these conventions, then you can use +:doc:`bundle inheritance ` to override files, +controllers or templates. For example, you can create a bundle - NewBundle +- and specify that it overrides AppBundle. When Symfony loads the +``AppBundle:Default:index`` controller, it will first look for the +``DefaultController`` class in NewBundle and, if it doesn't exist, then +look inside AppBundle. This means that one bundle can override almost any +part of another bundle! Do you understand now why Symfony is so flexible? Share your bundles between applications, store them locally or globally, your choice. @@ -245,37 +249,40 @@ Using Vendors Odds are that your application will depend on third-party libraries. Those should be stored in the ``vendor/`` directory. You should never touch anything in this directory, because it is exclusively managed by Composer. This directory -already contains the Symfony libraries, the SwiftMailer library, the Doctrine ORM, -the Twig templating system and some other third party libraries and bundles. +already contains the Symfony libraries, the SwiftMailer library, the Doctrine +ORM, the Twig templating system and some other third party libraries and +bundles. Understanding the Cache and Logs -------------------------------- -Symfony applications can contain several configuration files defined in several -formats (YAML, XML, PHP, etc.) Instead of parsing and combining all those files -for each request, Symfony uses its own cache system. In fact, the application -configuration is only parsed for the very first request and then compiled down -to plain PHP code stored in the ``app/cache/`` directory. +Symfony applications can contain several configuration files defined in +several formats (YAML, XML, PHP, etc.) Instead of parsing and combining +all those files for each request, Symfony uses its own cache system. In +fact, the application configuration is only parsed for the very first request +and then compiled down to plain PHP code stored in the ``app/cache/`` +directory. -In the development environment, Symfony is smart enough to update the cache when -you change a file. But in the production environment, to speed things up, it is -your responsibility to clear the cache when you update your code or change its -configuration. Execute this command to clear the cache in the ``prod`` environment: +In the development environment, Symfony is smart enough to update the cache +when you change a file. But in the production environment, to speed things +up, it is your responsibility to clear the cache when you update your code +or change its configuration. Execute this command to clear the cache in +the ``prod`` environment: .. code-block:: bash $ php app/console cache:clear --env=prod -When developing a web application, things can go wrong in many ways. The log -files in the ``app/logs/`` directory tell you everything about the requests +When developing a web application, things can go wrong in many ways. The +log files in the ``app/logs/`` directory tell you everything about the requests and help you fix the problem quickly. Using the Command Line Interface -------------------------------- Each application comes with a command line interface tool (``app/console``) -that helps you maintain your application. It provides commands that boost your -productivity by automating tedious and repetitive tasks. +that helps you maintain your application. It provides commands that boost +your productivity by automating tedious and repetitive tasks. Run it without any arguments to learn more about its capabilities: @@ -299,7 +306,7 @@ around as you see fit. And that's all for the quick tour. From testing to sending emails, you still need to learn a lot to become a Symfony master. Ready to dig into these -topics now? Look no further - go to the official :doc:`/book/index` and pick -any topic you want. +topics now? Look no further - go to the official :doc:`/book/index` and +pick any topic you want. .. _Composer: http://getcomposer.org diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index 309238e1db2..68649076bc7 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -1,18 +1,18 @@ The Big Picture =============== -Start using Symfony in 10 minutes! This chapter will walk you through the most -important concepts behind Symfony and explain how you can get started quickly -by showing you a simple project in action. +Start using Symfony in 10 minutes! This chapter will walk you through the +most important concepts behind Symfony and explain how you can get started +quickly by showing you a simple project in action. If you've used a web framework before, you should feel right at home with Symfony. If not, welcome to a whole new way of developing web applications. -The only technical requisite to follow this tutorial is to have **PHP 5.4 or higher -installed on your computer**. If you use a packaged PHP solution such as WAMP, -XAMP or MAMP, check out that they are using PHP 5.4 or a more recent version. -You can also execute the following command in your terminal or command console -to display the installed PHP version: +The only technical requisite to follow this tutorial is to have **PHP 5.4 +or higher installed on your computer**. If you use a packaged PHP solution +such as WAMP, XAMP or MAMP, check out that they are using PHP 5.4 or a more +recent version. You can also execute the following command in your terminal +or command console to display the installed PHP version: .. code-block:: bash @@ -23,9 +23,9 @@ to display the installed PHP version: Installing Symfony ------------------ -In the past, Symfony had to be installed manually for each new project. Now you -can use the **Symfony Installer**, which has to be installed the very first time -you use Symfony on a computer. +In the past, Symfony had to be installed manually for each new project. +Now you can use the **Symfony Installer**, which has to be installed the +very first time you use Symfony on a computer. On **Linux** and **Mac OS X** systems, execute the following console commands: @@ -35,8 +35,8 @@ On **Linux** and **Mac OS X** systems, execute the following console commands: $ sudo mv symfony.phar /usr/local/bin/symfony $ chmod a+x /usr/local/bin/symfony -After installing the Symfony installer, you'll have to open a new console window -to be able to execute the new ``symfony`` command: +After installing the Symfony installer, you'll have to open a new console +window to be able to execute the new ``symfony`` command: .. code-block:: bash @@ -48,19 +48,20 @@ On **Windows** systems, execute the following console command: c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar -This command downloads a file called ``symfony.phar`` which contains the Symfony -installer. Save or move that file to the directory where you create the Symfony -projects and then, execute the Symfony installer right away with this command: +This command downloads a file called ``symfony.phar`` which contains the +Symfony installer. Save or move that file to the directory where you create +the Symfony projects and then, execute the Symfony installer right away +with this command: .. code-block:: bash c:\> php symfony.phar -Creating Your First Symfony Project +Creating your First Symfony Project ----------------------------------- -Once the Symfony Installer is set up, use the ``new`` command to create new -Symfony projects. Let's create a new project called ``myproject``: +Once the Symfony Installer is set up, use the ``new`` command to create +new Symfony projects. Let's create a new project called ``myproject``: .. code-block:: bash @@ -70,9 +71,9 @@ Symfony projects. Let's create a new project called ``myproject``: # Windows c:\> php symfony.phar new myproject -This command downloads the latest Symfony stable version and creates an empty -project in the ``myproject/`` directory so you can start developing your -application right away. +This command downloads the latest Symfony stable version and creates an +empty project in the ``myproject/`` directory so you can start developing +your application right away. .. _running-symfony2: @@ -89,24 +90,25 @@ the project directory and executing this command: $ php app/console server:run Open your browser and access the ``http://localhost:8000`` URL to see the -Welcome page of Symfony: +welcome page of Symfony: .. image:: /images/quick_tour/welcome.png :align: center - :alt: Symfony Welcome Page + :alt: Symfony Welcome Page Congratulations! Your first Symfony project is up and running! .. note:: Instead of the welcome page, you may see a blank page or an error page. - This is caused by a directory permission misconfiguration. There are several - possible solutions depending on your operating system. All of them are - explained in the :ref:`Setting up Permissions ` - section of the official book. + This is caused by a directory permission misconfiguration. There are + several possible solutions depending on your operating system. All of + them are explained in the + :ref:`Setting up Permissions ` section + of the official book. -When you are finished working on your Symfony application, you can stop the -server with the ``server:stop`` command: +When you are finished working on your Symfony application, you can stop +the server with the ``server:stop`` command: .. code-block:: bash @@ -114,19 +116,19 @@ server with the ``server:stop`` command: .. tip:: - If you prefer a traditional web server such as Apache or Nginx, read the - :doc:`/cookbook/configuration/web_server_configuration` article. + If you prefer a traditional web server such as Apache or Nginx, read + the :doc:`/cookbook/configuration/web_server_configuration` article. Understanding the Fundamentals ------------------------------ -One of the main goals of a framework is to keep your code organized and to allow -your application to evolve easily over time by avoiding the mixing of database -calls, HTML tags and other PHP code in the same script. To achieve this goal -with Symfony, you'll first need to learn a few fundamental concepts. +One of the main goals of a framework is to keep your code organized and +to allow your application to evolve easily over time by avoiding the mixing +of database calls, HTML tags and other PHP code in the same script. To achieve +this goal with Symfony, you'll first need to learn a few fundamental concepts. -When developing a Symfony application, your responsibility as a developer is to -write the code that maps the user's *request* (e.g. ``http://localhost:8000/``) +When developing a Symfony application, your responsibility as a developer +is to write the code that maps the user's *request* (e.g. ``http://localhost:8000/``) to the *resource* associated with it (the ``Welcome to Symfony!`` HTML page). The code to execute is defined in **actions** and **controllers**. The mapping @@ -142,9 +144,9 @@ controllers, routes and templates. Actions and Controllers ~~~~~~~~~~~~~~~~~~~~~~~ -Open the ``src/AppBundle/Controller/DefaultController.php`` file and you'll see -the following code (for now, don't look at the ``@Route`` configuration because -that will be explained in the next section):: +Open the ``src/AppBundle/Controller/DefaultController.php`` file and you'll +see the following code (for now, don't look at the ``@Route`` configuration +because that will be explained in the next section):: namespace AppBundle\Controller; @@ -162,18 +164,18 @@ that will be explained in the next section):: } } -In Symfony applications, **controllers** are usually PHP classes whose names are -suffixed with the ``Controller`` word. In this example, the controller is called -``Default`` and the PHP class is called ``DefaultController``. +In Symfony applications, **controllers** are usually PHP classes whose names +are suffixed with the ``Controller`` word. In this example, the controller +is called ``Default`` and the PHP class is called ``DefaultController``. The methods defined in a controller are called **actions**, they are usually -associated with one URL of the application and their names are suffixed with -``Action``. In this example, the ``Default`` controller has only one action -called ``index`` and defined in the ``indexAction`` method. +associated with one URL of the application and their names are suffixed +with ``Action``. In this example, the ``Default`` controller has only one +action called ``index`` and defined in the ``indexAction`` method. -Actions are usually very short - around 10-15 lines of code - because they just -call other parts of the application to get or generate the needed information and -then they render a template to show the results to the user. +Actions are usually very short - around 10-15 lines of code - because they +just call other parts of the application to get or generate the needed +information and then they render a template to show the results to the user. In this example, the ``index`` action is practically empty because it doesn't need to call any other method. The action just renders a template with the @@ -183,11 +185,9 @@ Routing ~~~~~~~ Symfony routes each request to the action that handles it by matching the -requested URL against the paths configured by the application. Open again the -``src/AppBundle/Controller/DefaultController.php`` file and take a look at the -three lines of code above the ``indexAction`` method: - -.. code-block:: php +requested URL against the paths configured by the application. Open again +the ``src/AppBundle/Controller/DefaultController.php`` file and take a look +at the three lines of code above the ``indexAction`` method:: // src/AppBundle/Controller/DefaultController.php namespace AppBundle\Controller; @@ -206,47 +206,47 @@ three lines of code above the ``indexAction`` method: } } -These three lines define the routing configuration via the ``@Route()`` annotation. -A **PHP annotation** is a convenient way to configure a method without having to -write regular PHP code. Beware that annotation blocks start with ``/**``, whereas -regular PHP comments start with ``/*``. +These three lines define the routing configuration via the ``@Route()`` +annotation. A **PHP annotation** is a convenient way to configure a method +without having to write regular PHP code. Beware that annotation blocks +start with ``/**``, whereas regular PHP comments start with ``/*``. The first value of ``@Route()`` defines the URL that will trigger the execution -of the action. As you don't have to add the host of your application to the URL -(e.g. ```http://example.com``), these URLs are always relative and they are usually -called *paths*. In this case, the ``/`` path refers to the application homepage. -The second value of ``@Route()`` (e.g. ``name="homepage"``) is optional and sets -the name of this route. For now this name is not needed, but later it'll be useful -for linking pages. - -Considering all this, the ``@Route("/", name="homepage")`` annotation creates a -new route called ``homepage`` which makes Symfony execute the ``index`` action -of the ``Default`` controller when the user browses the ``/`` path of the application. +of the action. As you don't have to add the host of your application to +the URL (e.g. ```http://example.com``), these URLs are always relative and +they are usually called *paths*. In this case, the ``/`` path refers to +the application homepage. The second value of ``@Route()`` (e.g. +``name="homepage"``) is optional and sets the name of this route. For now +this name is not needed, but later it'll be useful for linking pages. + +Considering all this, the ``@Route("/", name="homepage")`` annotation creates +a new route called ``homepage`` which makes Symfony execute the ``index`` +action of the ``Default`` controller when the user browses the ``/`` path +of the application. .. tip:: - In addition to PHP annotations, routes can be configured in YAML, XML or - PHP files, as explained in :doc:`the Routing chapter of the Symfony book `. - This flexibility is one of the main features of Symfony, a framework that + In addition to PHP annotations, routes can be configured in YAML, XML + or PHP files, as explained in + :doc:`the Routing chapter of the Symfony book `. This + flexibility is one of the main features of Symfony, a framework that never imposes a particular configuration format on you. Templates ~~~~~~~~~ -The only content of the ``index`` action is this PHP instruction: - -.. code-block:: php +The only content of the ``index`` action is this PHP instruction:: return $this->render('default/index.html.twig'); The ``$this->render()`` method is a convenient shortcut to render a template. -Symfony provides some useful shortcuts to any controller extending from the -``Controller`` class. +Symfony provides some useful shortcuts to any controller extending from +the ``Controller`` class. By default, application templates are stored in the ``app/Resources/views/`` -directory. Therefore, the ``default/index.html.twig`` template corresponds to the -``app/Resources/views/default/index.html.twig``. Open that file and you'll see -the following code: +directory. Therefore, the ``default/index.html.twig`` template corresponds +to the ``app/Resources/views/default/index.html.twig``. Open that file and +you'll see the following code: .. code-block:: html+jinja @@ -257,9 +257,10 @@ the following code:

Welcome to Symfony!

{% endblock %} -This template is created with `Twig`_, a new template engine created for modern -PHP applications. The :doc:`second part of this tutorial ` -will introduce how templates work in Symfony. +This template is created with `Twig`_, a new template engine created for +modern PHP applications. The +:doc:`second part of this tutorial ` will introduce +how templates work in Symfony. .. _quick-tour-big-picture-environments: @@ -268,56 +269,58 @@ Working with Environments Now that you have a better understanding of how Symfony works, take a closer look at the bottom of any Symfony rendered page. You should notice a small -bar with the Symfony logo. This is the "Web Debug Toolbar", and it is a -Symfony developer's best friend! +bar with the Symfony logo. This is the "Web Debug Toolbar" and it is a Symfony +developer's best friend! .. image:: /images/quick_tour/web_debug_toolbar.png :align: center -But what you see initially is only the tip of the iceberg; click on any of the -bar sections to open the profiler and get much more detailed information about -the request, the query parameters, security details, and database queries: +But what you see initially is only the tip of the iceberg; click on any +of the bar sections to open the profiler and get much more detailed information +about the request, the query parameters, security details and database queries: .. image:: /images/quick_tour/profiler.png :align: center -This tool provides so much internal information about your application that you -may be worried about your visitors accessing sensible information. Symfony is -aware of this issue and for that reason, it won't display this bar when your -application is running in the production server. +This tool provides so much internal information about your application that +you may be worried about your visitors accessing sensible information. Symfony +is aware of this issue and for that reason, it won't display this bar when +your application is running in the production server. -How does Symfony know whether your application is running locally or on a -production server? Keep reading to discover the concept of **execution environments**. +How does Symfony know whether your application is running locally or on +a production server? Keep reading to discover the concept of **execution +environments**. .. _quick-tour-big-picture-environments-intro: What is an Environment? ~~~~~~~~~~~~~~~~~~~~~~~ -An :term:`Environment` represents a group of configurations that's used to run -your application. Symfony defines two environments by default: ``dev`` +An :term:`Environment` represents a group of configurations that's used +to run your application. Symfony defines two environments by default: ``dev`` (suited for when developing the application locally) and ``prod`` (optimized for when executing the application on production). -When you visit the ``http://localhost:8000`` URL in your browser, you're executing -your Symfony application in the ``dev`` environment. To visit your application -in the ``prod`` environment, visit the ``http://localhost:8000/app.php`` URL instead. -If you prefer to always show the ``dev`` environment in the URL, you can visit -``http://localhost:8000/app_dev.php`` URL. +When you visit the ``http://localhost:8000`` URL in your browser, you're +executing your Symfony application in the ``dev`` environment. To visit +your application in the ``prod`` environment, visit the ``http://localhost:8000/app.php`` +URL instead. If you prefer to always show the ``dev`` environment in the +URL, you can visit ``http://localhost:8000/app_dev.php`` URL. -The main difference between environments is that ``dev`` is optimized to provide -lots of information to the developer, which means worse application performance. -Meanwhile, ``prod`` is optimized to get the best performance, which means that -debug information is disabled, as well as the Web Debug Toolbar. +The main difference between environments is that ``dev`` is optimized to +provide lots of information to the developer, which means worse application +performance. Meanwhile, ``prod`` is optimized to get the best performance, +which means that debug information is disabled, as well as the Web Debug +Toolbar. -The other difference between environments is the configuration options used to -execute the application. When you access the ``dev`` environment, Symfony loads -the ``app/config/config_dev.yml`` configuration file. When you access the ``prod`` -environment, Symfony loads ``app/config/config_prod.yml`` file. +The other difference between environments is the configuration options used +to execute the application. When you access the ``dev`` environment, Symfony +loads the ``app/config/config_dev.yml`` configuration file. When you access +the ``prod`` environment, Symfony loads ``app/config/config_prod.yml`` file. -Typically, the environments share a large amount of configuration options. For -that reason, you put your common configuration in ``config.yml`` and override -the specific configuration file for each environment where necessary: +Typically, the environments share a large amount of configuration options. +For that reason, you put your common configuration in ``config.yml`` and +override the specific configuration file for each environment where necessary: .. code-block:: yaml @@ -339,10 +342,10 @@ For more details on environments, see Final Thoughts -------------- -Congratulations! You've had your first taste of Symfony code. That wasn't so -hard, was it? There's a lot more to explore, but you should already see how -Symfony makes it really easy to implement web sites better and faster. If you -are eager to learn more about Symfony, dive into the next section: +Congratulations! You've had your first taste of Symfony code. That wasn't +so hard, was it? There's a lot more to explore, but you should already see +how Symfony makes it really easy to implement web sites better and faster. +If you are eager to learn more about Symfony, dive into the next section: ":doc:`The View `". .. _Composer: https://getcomposer.org/ diff --git a/quick_tour/the_controller.rst b/quick_tour/the_controller.rst index bc90f0af99b..2aadff900d4 100644 --- a/quick_tour/the_controller.rst +++ b/quick_tour/the_controller.rst @@ -1,21 +1,22 @@ The Controller ============== -Still here after the first two parts? You are already becoming a Symfony fan! -Without further ado, discover what controllers can do for you. +Still here after the first two parts? You are already becoming a Symfony +fan! Without further ado, discover what controllers can do for you. Returning Raw Responses ----------------------- -Symfony defines itself as a Request-Response framework. When the user makes a -request to your application, Symfony creates a ``Request`` object to encapsulate -all the information related to that request. Similarly, the result of executing -any action of any controller is the creation of a ``Response`` object which -Symfony uses to generate the HTML content returned to the user. +Symfony defines itself as a Request-Response framework. When the user makes +a request to your application, Symfony creates a ``Request`` object to +encapsulate all the information related to that request. Similarly, the +result of executing any action of any controller is the creation of a +``Response`` object which Symfony uses to generate the HTML content returned +to the user. So far, all the actions shown in this tutorial used the ``$this->render()`` -shortcut to return a rendered response as result. In case you need it, you can -also create a raw ``Response`` object to return any text content:: +shortcut to return a rendered response as result. In case you need it, you +can also create a raw ``Response`` object to return any text content:: // src/AppBundle/Controller/DefaultController.php namespace AppBundle\Controller; @@ -38,18 +39,19 @@ also create a raw ``Response`` object to return any text content:: Route Parameters ---------------- -Most of the time, the URLs of applications include variable parts on them. If you -are creating for example a blog application, the URL to display the articles should -include their title or some other unique identifier to let the application know -the exact article to display. +Most of the time, the URLs of applications include variable parts on them. +If you are creating for example a blog application, the URL to display the +articles should include their title or some other unique identifier to let +the application know the exact article to display. -In Symfony applications, the variable parts of the routes are enclosed in curly -braces (e.g. ``/blog/read/{article_title}/``). Each variable part is assigned a -unique name that can be used later in the controller to retrieve each value. +In Symfony applications, the variable parts of the routes are enclosed in +curly braces (e.g. ``/blog/read/{article_title}/``). Each variable part +is assigned a unique name that can be used later in the controller to retrieve +each value. Let's create a new action with route variables to show this feature in action. -Open the ``src/AppBundle/Controller/DefaultController.php`` file and add a new -method called ``helloAction`` with the following content:: +Open the ``src/AppBundle/Controller/DefaultController.php`` file and add +a new method called ``helloAction`` with the following content:: // src/AppBundle/Controller/DefaultController.php namespace AppBundle\Controller; @@ -72,13 +74,14 @@ method called ``helloAction`` with the following content:: } } -Open your browser and access the ``http://localhost:8000/hello/fabien`` URL to -see the result of executing this new action. Instead of the action result, you'll -see an error page. As you probably guessed, the cause of this error is that we're -trying to render a template (``default/hello.html.twig``) that doesn't exist yet. +Open your browser and access the ``http://localhost:8000/hello/fabien`` +URL to see the result of executing this new action. Instead of the action +result, you'll see an error page. As you probably guessed, the cause of +this error is that we're trying to render a template +(``default/hello.html.twig``) that doesn't exist yet. -Create the new ``app/Resources/views/default/hello.html.twig`` template with the -following content: +Create the new ``app/Resources/views/default/hello.html.twig`` template +with the following content: .. code-block:: html+jinja @@ -89,12 +92,13 @@ following content:

Hi {{ name }}! Welcome to Symfony!

{% endblock %} -Browse again the ``http://localhost:8000/hello/fabien`` URL and you'll see this -new template rendered with the information passed by the controller. If you -change the last part of the URL (e.g. ``http://localhost:8000/hello/thomas``) -and reload your browser, the page will display a different message. And if you -remove the last part of the URL (e.g. ``http://localhost:8000/hello``), Symfony -will display an error because the route expects a name and you haven't provided it. +Browse again the ``http://localhost:8000/hello/fabien`` URL and you'll see +this new template rendered with the information passed by the controller. +If you change the last part of the URL (e.g. +``http://localhost:8000/hello/thomas``) and reload your browser, the page +will display a different message. And if you remove the last part of the +URL (e.g. ``http://localhost:8000/hello``), Symfony will display an error +because the route expects a name and you haven't provided it. Using Formats ------------- @@ -105,8 +109,8 @@ there are plenty of different formats to choose from. Supporting those formats in Symfony is straightforward thanks to a special variable called ``_format`` which stores the format requested by the user. -Tweak the ``hello`` route by adding a new ``_format`` variable with ``html`` as -its default value:: +Tweak the ``hello`` route by adding a new ``_format`` variable with ``html`` +as its default value:: // src/AppBundle/Controller/DefaultController.php use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; @@ -124,9 +128,9 @@ its default value:: )); } -Obviously, when you support several request formats, you have to provide a -template for each of the supported formats. In this case, you should create a -new ``hello.xml.twig`` template: +Obviously, when you support several request formats, you have to provide +a template for each of the supported formats. In this case, you should create +a new ``hello.xml.twig`` template: .. code-block:: xml+php @@ -135,16 +139,16 @@ new ``hello.xml.twig`` template: {{ name }} -Now, when you browse to ``http://localhost:8000/hello/fabien``, you'll see the -regular HTML page because ``html`` is the default format. When visiting -``http://localhost:8000/hello/fabien.html`` you'll get again the HTML page, this -time because you explicitly asked for the ``html`` format. Lastly, if you visit -``http://localhost:8000/hello/fabien.xml`` you'll see the new XML template rendered -in your browser. +Now, when you browse to ``http://localhost:8000/hello/fabien``, you'll see +the regular HTML page because ``html`` is the default format. When visiting +``http://localhost:8000/hello/fabien.html`` you'll get again the HTML page, +this time because you explicitly asked for the ``html`` format. Lastly, +if you visit ``http://localhost:8000/hello/fabien.xml`` you'll see the new +XML template rendered in your browser. That's all there is to it. For standard formats, Symfony will also -automatically choose the best ``Content-Type`` header for the response. To -restrict the formats supported by a given action, use the ``requirements`` +automatically choose the best ``Content-Type`` header for the response. +To restrict the formats supported by a given action, use the ``requirements`` option of the ``@Route()`` annotation:: // src/AppBundle/Controller/DefaultController.php @@ -169,8 +173,8 @@ option of the ``@Route()`` annotation:: The ``hello`` action will now match URLs like ``/hello/fabien.xml`` or ``/hello/fabien.json``, but it will show a 404 error if you try to get URLs -like ``/hello/fabien.js``, because the value of the ``_format`` variable doesn't -meet its requirements. +like ``/hello/fabien.js``, because the value of the ``_format`` variable +doesn't meet its requirements. .. _redirecting-and-forwarding: @@ -192,15 +196,16 @@ method:: } } -The ``redirectToRoute()`` method takes as arguments the route name and an optional -array of parameters and redirects the user to the URL generated with those arguments. +The ``redirectToRoute()`` method takes as arguments the route name and an +optional array of parameters and redirects the user to the URL generated +with those arguments. Displaying Error Pages ---------------------- Errors will inevitably happen during the execution of every web application. -In the case of ``404`` errors, Symfony includes a handy shortcut that you can -use in your controllers:: +In the case of ``404`` errors, Symfony includes a handy shortcut that you +can use in your controllers:: // src/AppBundle/Controller/DefaultController.php // ... @@ -217,8 +222,8 @@ use in your controllers:: } } -For ``500`` errors, just throw a regular PHP exception inside the controller and -Symfony will transform it into a proper ``500`` error page:: +For ``500`` errors, just throw a regular PHP exception inside the controller +and Symfony will transform it into a proper ``500`` error page:: // src/AppBundle/Controller/DefaultController.php // ... @@ -238,12 +243,12 @@ Symfony will transform it into a proper ``500`` error page:: Getting Information from the Request ------------------------------------ -Sometimes your controllers need to access the information related to the user -request, such as their preferred language, IP address or the URL query parameters. -To get access to this information, add a new argument of type ``Request`` to the -action. The name of this new argument doesn't matter, but it must be preceded -by the ``Request`` type in order to work (don't forget to add the new ``use`` -statement that imports this ``Request`` class):: +Sometimes your controllers need to access the information related to the +user request, such as their preferred language, IP address or the URL query +parameters. To get access to this information, add a new argument of type +``Request`` to the action. The name of this new argument doesn't matter, +but it must be preceded by the ``Request`` type in order to work (don't +forget to add the new ``use`` statement that imports this ``Request`` class):: // src/AppBundle/Controller/DefaultController.php namespace AppBundle\Controller; @@ -285,10 +290,10 @@ In a template, you can also access the ``Request`` object via the special Persisting Data in the Session ------------------------------ -Even if the HTTP protocol is stateless, Symfony provides a nice session object -that represents the client (be it a real person using a browser, a bot, or a -web service). Between two requests, Symfony stores the attributes in a cookie -by using native PHP sessions. +Even if the HTTP protocol is stateless, Symfony provides a nice session +object that represents the client (be it a real person using a browser, +a bot, or a web service). Between two requests, Symfony stores the attributes +in a cookie by using native PHP sessions. Storing and retrieving information from the session can be easily achieved from any controller:: @@ -309,9 +314,9 @@ from any controller:: $foo = $session->get('foo', 'default_value'); } -You can also store "flash messages" that will auto-delete after the next request. -They are useful when you need to set a success message before redirecting the -user to another page (which will then show the message):: +You can also store "flash messages" that will auto-delete after the next +request. They are useful when you need to set a success message before +redirecting the user to another page (which will then show the message):: public function indexAction(Request $request) { @@ -332,8 +337,8 @@ And you can display the flash message in the template like this: Final Thoughts -------------- -That's all there is to it, and I'm not even sure you'll have spent the full -10 minutes. You were briefly introduced to bundles in the first part, and all the -features you've learned about so far are part of the core framework bundle. -But thanks to bundles, everything in Symfony can be extended or replaced. -That's the topic of the :doc:`next part of this tutorial `. +That's all there is to it and I'm not even sure you'll have spent the full +10 minutes. You were briefly introduced to bundles in the first part and +all the features you've learned about so far are part of the core framework +bundle. But thanks to bundles, everything in Symfony can be extended or +replaced. That's the topic of the :doc:`next part of this tutorial `. diff --git a/quick_tour/the_view.rst b/quick_tour/the_view.rst index 975418f480d..d05044037aa 100644 --- a/quick_tour/the_view.rst +++ b/quick_tour/the_view.rst @@ -3,31 +3,31 @@ The View After reading the first part of this tutorial, you have decided that Symfony was worth another 10 minutes. In this second part, you will learn more about -`Twig`_, the fast, flexible, and secure template engine for PHP applications. -Twig makes your templates more readable and concise; it also makes them more -friendly for web designers. +`Twig`_, the fast, flexible and secure template engine for PHP applications. +Twig makes your templates more readable and concise; it also makes them +more friendly for web designers. -Getting familiar with Twig +Getting Familiar with Twig -------------------------- The official `Twig documentation`_ is the best resource to learn everything -about this template engine. This section just gives you a quick overview of -its main concepts. +about this template engine. This section just gives you a quick overview +of its main concepts. -A Twig template is a text file that can generate any type of content (HTML, CSS, -JavaScript, XML, CSV, LaTeX, etc.) Twig elements are separated from the rest of -the template contents using any of these delimiters: +A Twig template is a text file that can generate any type of content (HTML, +CSS, JavaScript, XML, CSV, LaTeX, etc.) Twig elements are separated from +the rest of the template contents using any of these delimiters: ``{{ ... }}`` Prints the content of a variable or the result of evaluating an expression; ``{% ... %}`` - Controls the logic of the template; it is used for example to execute ``for`` - loops and ``if`` statements. + Controls the logic of the template; it is used for example to execute + ``for`` loops and ``if`` statements. ``{# ... #}`` - Allows including comments inside templates. Contrary to HTML comments, they - aren't included in the rendered template. + Allows including comments inside templates. Contrary to HTML comments, + they aren't included in the rendered template. Below is a minimal template that illustrates a few basics, using two variables ``page_title`` and ``navigation``, which would be passed into the template: @@ -50,34 +50,41 @@ Below is a minimal template that illustrates a few basics, using two variables -To render a template in Symfony, use the ``render`` method from within a controller. -If the template needs variables to generate its contents, pass them as an array -using the second optional argument:: +To render a template in Symfony, use the ``render`` method from within a +controller. If the template needs variables to generate its contents, pass +them as an array using the second optional argument:: $this->render('default/index.html.twig', array( 'variable_name' => 'variable_value', )); Variables passed to a template can be strings, arrays or even objects. Twig -abstracts the difference between them and lets you access "attributes" of a -variable with the dot (``.``) notation. The following code listing shows how to -display the content of a variable passed by the controller depending on its type: +abstracts the difference between them and lets you access "attributes" of +a variable with the dot (``.``) notation. The following code listing shows +how to display the content of a variable passed by the controller depending +on its type: .. code-block:: jinja {# 1. Simple variables #} - {# $this->render('template.html.twig', array('name' => 'Fabien') ) #} + {# $this->render('template.html.twig', array( + 'name' => 'Fabien') + ) #} {{ name }} {# 2. Arrays #} - {# $this->render('template.html.twig', array('user' => array('name' => 'Fabien')) ) #} + {# $this->render('template.html.twig', array( + 'user' => array('name' => 'Fabien')) + ) #} {{ user.name }} {# alternative syntax for arrays #} {{ user['name'] }} {# 3. Objects #} - {# $this->render('template.html.twig', array('user' => new User('Fabien')) ) #} + {# $this->render('template.html.twig', array( + 'user' => new User('Fabien')) + ) #} {{ user.name }} {{ user.getName }} @@ -88,14 +95,14 @@ display the content of a variable passed by the controller depending on its type Decorating Templates -------------------- -More often than not, templates in a project share common elements, like the -well-known header and footer. Twig solves this problem elegantly with a concept -called "template inheritance". This feature allows you to build a base template -that contains all the common elements of your site and defines "blocks" of contents -that child templates can override. +More often than not, templates in a project share common elements, like +the well-known header and footer. Twig solves this problem elegantly with +a concept called "template inheritance". This feature allows you to build +a base template that contains all the common elements of your site and +defines "blocks" of contents that child templates can override. -The ``index.html.twig`` template uses the ``extends`` tag to indicate that it -inherits from the ``base.html.twig`` template: +The ``index.html.twig`` template uses the ``extends`` tag to indicate that +it inherits from the ``base.html.twig`` template: .. code-block:: html+jinja @@ -106,8 +113,8 @@ inherits from the ``base.html.twig`` template:

Welcome to Symfony!

{% endblock %} -Open the ``app/Resources/views/base.html.twig`` file that corresponds to the -``base.html.twig`` template and you'll find the following Twig code: +Open the ``app/Resources/views/base.html.twig`` file that corresponds to +the ``base.html.twig`` template and you'll find the following Twig code: .. code-block:: html+jinja @@ -126,16 +133,17 @@ Open the ``app/Resources/views/base.html.twig`` file that corresponds to the -The ``{% block %}`` tags tell the template engine that a child template may -override those portions of the template. In this example, the ``index.html.twig`` -template overrides the ``body`` block, but not the ``title`` block, which will -display the default content defined in the ``base.html.twig`` template. +The ``{% block %}`` tags tell the template engine that a child template +may override those portions of the template. In this example, the +``index.html.twig`` template overrides the ``body`` block, but not the +``title`` block, which will display the default content defined in the +``base.html.twig`` template. -Using Tags, Filters, and Functions ----------------------------------- +Using Tags, Filters and Functions +--------------------------------- -One of the best features of Twig is its extensibility via tags, filters, and -functions. Take a look at the following sample template that uses filters +One of the best features of Twig is its extensibility via tags, filters +and functions. Take a look at the following sample template that uses filters extensively to modify the information before displaying it to the user: .. code-block:: jinja @@ -154,8 +162,8 @@ about filters, functions and tags. Including other Templates ~~~~~~~~~~~~~~~~~~~~~~~~~ -The best way to share a snippet of code between several templates is to create a -new template fragment that can then be included from other templates. +The best way to share a snippet of code between several templates is to +create a new template fragment that can then be included from other templates. Imagine that we want to display ads on some pages of our application. First, create a ``banner.html.twig`` template: @@ -167,8 +175,8 @@ create a ``banner.html.twig`` template: ... -To display this ad on any page, include the ``banner.html.twig`` template using -the ``include()`` function: +To display this ad on any page, include the ``banner.html.twig`` template +using the ``include()`` function: .. code-block:: html+jinja @@ -185,13 +193,13 @@ Embedding other Controllers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ And what if you want to embed the result of another controller in a template? -That's very useful when working with Ajax, or when the embedded template needs -some variable not available in the main template. +That's very useful when working with Ajax, or when the embedded template +needs some variable not available in the main template. -Suppose you've created a ``topArticlesAction`` controller method to display the -most popular articles of your website. If you want to "render" the result of -that method (usually some HTML content) inside the ``index`` template, use the -``render()`` function: +Suppose you've created a ``topArticlesAction`` controller method to display +the most popular articles of your website. If you want to "render" the result +of that method (usually some HTML content) inside the ``index`` template, +use the ``render()`` function: .. code-block:: jinja @@ -200,7 +208,8 @@ that method (usually some HTML content) inside the ``index`` template, use the Here, the ``render()`` and ``controller()`` functions use the special ``AppBundle:Default:topArticles`` syntax to refer to the ``topArticlesAction`` -action of the ``Default`` controller (the ``AppBundle`` part will be explained later):: +action of the ``Default`` controller (the ``AppBundle`` part will be explained +later):: // src/AppBundle/Controller/DefaultController.php @@ -224,15 +233,15 @@ Creating Links between Pages Creating links between pages is a must for web applications. Instead of hardcoding URLs in templates, the ``path`` function knows how to generate -URLs based on the routing configuration. That way, all your URLs can be easily -updated by just changing the configuration: +URLs based on the routing configuration. That way, all your URLs can be +easily updated by just changing the configuration: .. code-block:: html+jinja Return to homepage -The ``path`` function takes the route name as the first argument and you can -optionally pass an array of route parameters as the second argument. +The ``path`` function takes the route name as the first argument and you +can optionally pass an array of route parameters as the second argument. .. tip:: @@ -243,7 +252,7 @@ optionally pass an array of route parameters as the second argument. Including Assets: Images, JavaScripts and Stylesheets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -What would the Internet be without images, JavaScripts, and stylesheets? +What would the Internet be without images, JavaScripts and stylesheets? Symfony provides the ``asset`` function to deal with them easily: .. code-block:: jinja @@ -256,9 +265,9 @@ The ``asset()`` function looks for the web assets inside the ``web/`` directory. If you store them in another directory, read :doc:`this article ` to learn how to manage web assets. -Using the ``asset`` function, your application is more portable. The reason is -that you can move the application root directory anywhere under your web root -directory without changing anything in your template's code. +Using the ``asset`` function, your application is more portable. The reason +is that you can move the application root directory anywhere under your +web root directory without changing anything in your template's code. Final Thoughts -------------- @@ -269,12 +278,12 @@ extensible way. You have only been working with Symfony for about 20 minutes, but you can already do pretty amazing stuff with it. That's the power of Symfony. Learning -the basics is easy, and you will soon learn that this simplicity is hidden +the basics is easy and you will soon learn that this simplicity is hidden under a very flexible architecture. -But I'm getting ahead of myself. First, you need to learn more about the controller -and that's exactly the topic of the :doc:`next part of this tutorial `. -Ready for another 10 minutes with Symfony? +But I'm getting ahead of myself. First, you need to learn more about the +controller and that's exactly the topic of the :doc:`next part of this tutorial +`. Ready for another 10 minutes with Symfony? .. _Twig: http://twig.sensiolabs.org/ .. _Twig documentation: http://twig.sensiolabs.org/documentation