From e0437ea9be5104f5f677b124535c793280272a51 Mon Sep 17 00:00:00 2001 From: manelselles Date: Mon, 13 Apr 2015 17:55:13 +0200 Subject: [PATCH 01/17] Use $this->getRootDir() instead of __DIR__ Use $this->getRootDir() when loading the configuration file from AppKernel. Symfony standard version uses $this->getRootDir() so we should have the same version on both sites. --- cookbook/configuration/environments.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/configuration/environments.rst b/cookbook/configuration/environments.rst index 751f5971ca1..1ef61ce437f 100644 --- a/cookbook/configuration/environments.rst +++ b/cookbook/configuration/environments.rst @@ -45,7 +45,7 @@ class: public function registerContainerConfiguration(LoaderInterface $loader) { - $loader->load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml'); + $loader->load($this->getRootDir().'/config/config_'.$this->getEnvironment().'.yml'); } } From 0209681dfd548ff0eaacc96add423564c2eea15e Mon Sep 17 00:00:00 2001 From: manelselles Date: Mon, 13 Apr 2015 21:09:03 +0200 Subject: [PATCH 02/17] Update configuration_organization.rst --- cookbook/configuration/configuration_organization.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cookbook/configuration/configuration_organization.rst b/cookbook/configuration/configuration_organization.rst index 62311e7c515..5473a4c06b1 100644 --- a/cookbook/configuration/configuration_organization.rst +++ b/cookbook/configuration/configuration_organization.rst @@ -23,7 +23,7 @@ class:: public function registerContainerConfiguration(LoaderInterface $loader) { - $loader->load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml'); + $loader->load($this->getRootDir().'/config/config_'.$this->getEnvironment().'.yml'); } } @@ -101,7 +101,7 @@ method:: public function registerContainerConfiguration(LoaderInterface $loader) { - $loader->load(__DIR__.'/config/'.$this->getEnvironment().'/config.yml'); + $loader->load($this->getRootDir().'/config/'.$this->getEnvironment().'/config.yml'); } } @@ -199,7 +199,7 @@ make Symfony aware of the new file organization:: public function registerContainerConfiguration(LoaderInterface $loader) { - $loader->load(__DIR__.'/config/environments/'.$this->getEnvironment().'.yml'); + $loader->load($this->getRootDir().'/config/environments/'.$this->getEnvironment().'.yml'); } } From 6964bff38fbf5fc520912ab4bc42ca8eae52c4c3 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Fri, 17 Apr 2015 06:07:22 -0400 Subject: [PATCH 03/17] Fixing a bad bcrypt string using http://www.bcrypt-generator.com/ --- cookbook/security/entity_provider.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cookbook/security/entity_provider.rst b/cookbook/security/entity_provider.rst index a46fab48d02..90c55eaf5dc 100644 --- a/cookbook/security/entity_provider.rst +++ b/cookbook/security/entity_provider.rst @@ -297,11 +297,11 @@ and password ``admin`` (which has been encoded). .. code-block:: bash $ mysql> SELECT * FROM app_users; - +----+----------+------------------------------------------+--------------------+-----------+ - | id | username | password | email | is_active | - +----+----------+------------------------------------------+--------------------+-----------+ - | 1 | admin | d033e22ae348aeb5660fc2140aec35850c4da997 | admin@example.com | 1 | - +----+----------+------------------------------------------+--------------------+-----------+ + +----+----------+--------------------------------------------------------------+--------------------+-----------+ + | id | username | password | email | is_active | + +----+----------+--------------------------------------------------------------+--------------------+-----------+ + | 1 | admin | $2a$08$jHZj/wJfcVKlIwr5AvR78euJxYK7Ku5kURNhNx.7.CSIJ3Pq6LEPC | admin@example.com | 1 | + +----+----------+--------------------------------------------------------------+--------------------+-----------+ .. sidebar:: Do you need to a Salt property? From 4ce1a948005f262369d02f3e2ddd3c91e2c0da4c Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Sun, 19 Apr 2015 00:28:06 +0200 Subject: [PATCH 04/17] Change 'xliff' extensions and loader name to 'xlf' --- best_practices/i18n.rst | 2 +- book/translation.rst | 14 +++++++------- components/translation/introduction.rst | 10 +++++----- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/best_practices/i18n.rst b/best_practices/i18n.rst index 5190af0a4ba..54eb9d7b59f 100644 --- a/best_practices/i18n.rst +++ b/best_practices/i18n.rst @@ -80,7 +80,7 @@ English in the application would be: .. code-block:: xml - + diff --git a/book/translation.rst b/book/translation.rst index 985c088cf53..a4955b05801 100644 --- a/book/translation.rst +++ b/book/translation.rst @@ -127,7 +127,7 @@ different formats, XLIFF being the recommended format: .. code-block:: xml - + @@ -359,18 +359,18 @@ must be named according to the following path: ``domain.locale.loader``: * **locale**: The locale that the translations are for (e.g. ``en_GB``, ``en``, etc); -* **loader**: How Symfony should load and parse the file (e.g. ``xliff``, +* **loader**: How Symfony should load and parse the file (e.g. ``xlf``, ``php``, ``yml``, etc). The loader can be the name of any registered loader. By default, Symfony provides many loaders, including: -* ``xliff``: XLIFF file; +* ``xlf``: XLIFF file; * ``php``: PHP file; * ``yml``: YAML file. The choice of which loader to use is entirely up to you and is a matter of -taste. The recommended option is to use ``xliff`` for translations. +taste. The recommended option is to use ``xlf`` for translations. For more options, see :ref:`component-translator-message-catalogs`. .. note:: @@ -400,10 +400,10 @@ key ``Symfony is great``. To find the French translation, Symfony actually checks translation resources for several locales: #. First, Symfony looks for the translation in a ``fr_FR`` translation resource - (e.g. ``messages.fr_FR.xliff``); + (e.g. ``messages.fr_FR.xlf``); #. If it wasn't found, Symfony looks for the translation in a ``fr`` translation - resource (e.g. ``messages.fr.xliff``); + resource (e.g. ``messages.fr.xlf``); #. If the translation still isn't found, Symfony uses the ``fallbacks`` configuration parameter, which defaults to ``en`` (see `Configuration`_). @@ -661,7 +661,7 @@ bundle. .. code-block:: xml - + diff --git a/components/translation/introduction.rst b/components/translation/introduction.rst index 02cb543424b..21ef071c21f 100644 --- a/components/translation/introduction.rst +++ b/components/translation/introduction.rst @@ -188,13 +188,13 @@ organization, translations were split into three different domains: loaded like this:: // ... - $translator->addLoader('xliff', new XliffFileLoader()); + $translator->addLoader('xlf', new XliffFileLoader()); - $translator->addResource('xliff', 'messages.fr.xliff', 'fr_FR'); - $translator->addResource('xliff', 'admin.fr.xliff', 'fr_FR', 'admin'); + $translator->addResource('xlf', 'messages.fr.xlf', 'fr_FR'); + $translator->addResource('xlf', 'admin.fr.xlf', 'fr_FR', 'admin'); $translator->addResource( - 'xliff', - 'navigation.fr.xliff', + 'xlf', + 'navigation.fr.xlf', 'fr_FR', 'navigation' ); From 116047c1b772de3c59c68e58c270a6552e4be798 Mon Sep 17 00:00:00 2001 From: Maxime Horcholle Date: Mon, 20 Apr 2015 17:13:48 +0200 Subject: [PATCH 05/17] Add missing caching drivers --- reference/configuration/doctrine.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index f5cc9e3dd09..f16f194abe9 100644 --- a/reference/configuration/doctrine.rst +++ b/reference/configuration/doctrine.rst @@ -294,8 +294,8 @@ certain classes, but those are for very advanced use-cases only. Caching Drivers ~~~~~~~~~~~~~~~ -For the caching drivers you can specify the values "array", "apc", "memcache", -"memcached", "xcache" or "service". +For the caching drivers you can specify the values ``array``, ``apc``, ``memcache``, +``memcached``, ``redis``, ``wincache``, ``zenddata``, ``xcache`` or ``service``. The following example shows an overview of the caching configurations: From 7fb47bfc6a9be273e4386a575d0e558a3b0f423c Mon Sep 17 00:00:00 2001 From: David Fuhr Date: Tue, 21 Apr 2015 11:31:46 +0200 Subject: [PATCH 06/17] Link twig constant function The link was already created but must have been lost in some update. --- best_practices/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst index ff1d8d05428..5c99a71f128 100644 --- a/best_practices/configuration.rst +++ b/best_practices/configuration.rst @@ -126,7 +126,7 @@ everywhere in your application. When using parameters, they are only available from places with access to the Symfony container. Constants can be used for example in your Twig templates thanks to the -``constant()`` function: +`constant() function`_: .. code-block:: html+jinja From a63b9b9c235519aac62dcf739975ca1c557737c7 Mon Sep 17 00:00:00 2001 From: Sorin Dumitrescu Date: Tue, 21 Apr 2015 20:30:16 +0300 Subject: [PATCH 07/17] Added missing link in "Sections" --- components/security/introduction.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/components/security/introduction.rst b/components/security/introduction.rst index 7d0cec88d74..15a688086ce 100644 --- a/components/security/introduction.rst +++ b/components/security/introduction.rst @@ -25,5 +25,6 @@ Sections * :doc:`/components/security/firewall` * :doc:`/components/security/authentication` * :doc:`/components/security/authorization` +* :doc:`/components/security/secure_tools` .. _Packagist: https://packagist.org/packages/symfony/security From d677c963f298da14533e154d8edbea71d0951e13 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 23 Apr 2015 08:34:04 +0200 Subject: [PATCH 08/17] Updated the cookbook about Composer installation --- cookbook/composer.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/cookbook/composer.rst b/cookbook/composer.rst index d57624c4a29..4cfd7282a30 100644 --- a/cookbook/composer.rst +++ b/cookbook/composer.rst @@ -4,8 +4,12 @@ Installing Composer =================== -`Composer`_ is the package manager used by modern PHP applications and the -recommended way to install Symfony2. +`Composer`_ is the package manager used by modern PHP applications. Use Composer +to manage dependencies in your Symfony applications and to install Symfony Components +in your PHP projects. + +It's recommended to install Composer globally in your system as explained in the +following sections. Install Composer on Linux and Mac OS X -------------------------------------- @@ -37,8 +41,8 @@ the instructions. Learn more ---------- -You can read more about Composer in `its documentation`_. +Read the `Composer documentation`_ to learn more about its usage and features. .. _`Composer`: https://getcomposer.org/ .. _`getcomposer.org/download`: https://getcomposer.org/download -.. _`its documentation`: https://getcomposer.org/doc/00-intro.md +.. _`Composer documentation`: https://getcomposer.org/doc/00-intro.md From f33b10de86ef58b054db2ac714c4c8c216451e7f Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Sun, 26 Apr 2015 02:15:18 +0200 Subject: [PATCH 09/17] [Reference] Fix order of config blocks --- reference/constraints/Image.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/reference/constraints/Image.rst b/reference/constraints/Image.rst index b73e75ac2e4..f19aa727d02 100644 --- a/reference/constraints/Image.rst +++ b/reference/constraints/Image.rst @@ -159,17 +159,6 @@ following code: .. configuration-block:: - .. code-block:: yaml - - # src/Acme/BlogBundle/Resources/config/validation.yml - Acme\BlogBundle\Entity\Author - properties: - headshot: - - Image: - allowLandscape: false - allowPortrait: false - - .. code-block:: php-annotations // src/Acme/BlogBundle/Entity/Author.php @@ -188,6 +177,16 @@ following code: protected $headshot; } + .. code-block:: yaml + + # src/Acme/BlogBundle/Resources/config/validation.yml + Acme\BlogBundle\Entity\Author + properties: + headshot: + - Image: + allowLandscape: false + allowPortrait: false + .. code-block:: xml From 4240b4b8441bc997819b51e75adcffbba64736c0 Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Sun, 26 Apr 2015 02:37:14 +0200 Subject: [PATCH 10/17] [Reference] Fix missing comma in constraint annotation --- reference/constraints/Image.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/Image.rst b/reference/constraints/Image.rst index f19aa727d02..e128a192987 100644 --- a/reference/constraints/Image.rst +++ b/reference/constraints/Image.rst @@ -170,7 +170,7 @@ following code: { /** * @Assert\Image( - * allowLandscape = false + * allowLandscape = false, * allowPortrait = false * ) */ From de5cbc594ea43b845ece7b7af2de34664e2f4876 Mon Sep 17 00:00:00 2001 From: Balamung Date: Wed, 15 Apr 2015 09:33:12 +0200 Subject: [PATCH 11/17] Rebase #5182 --- cookbook/configuration/web_server_configuration.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/configuration/web_server_configuration.rst b/cookbook/configuration/web_server_configuration.rst index 9a8e2955009..8aea0992cff 100644 --- a/cookbook/configuration/web_server_configuration.rst +++ b/cookbook/configuration/web_server_configuration.rst @@ -52,7 +52,7 @@ The **minimum configuration** to get your application running under Apache is: # uncomment the following lines if you install assets as symlinks # or run into problems when compiling LESS/Sass/CoffeScript assets # - # Option FollowSymlinks + # Options FollowSymlinks # ErrorLog /var/log/apache2/project_error.log @@ -90,7 +90,7 @@ and increase web server performance: # uncomment the following lines if you install assets as symlinks # or run into problems when compiling LESS/Sass/CoffeScript assets # - # Option FollowSymlinks + # Options FollowSymlinks # ErrorLog /var/log/apache2/project_error.log @@ -194,7 +194,7 @@ directive to pass requests for PHP files to PHP FPM: # uncomment the following lines if you install assets as symlinks # or run into problems when compiling LESS/Sass/CoffeScript assets # - # Option FollowSymlinks + # Options FollowSymlinks # ErrorLog /var/log/apache2/project_error.log @@ -230,7 +230,7 @@ should look something like this: # uncomment the following lines if you install assets as symlinks # or run into problems when compiling LESS/Sass/CoffeScript assets # - # Option FollowSymlinks + # Options FollowSymlinks # ErrorLog /var/log/apache2/project_error.log From fd133c75c41022da191ce00016e38c19ca69c5dc Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 17 Apr 2015 16:50:12 +0200 Subject: [PATCH 12/17] Fixed things found by the docbot --- quick_tour/the_architecture.rst | 129 +++++++++--------- quick_tour/the_big_picture.rst | 235 ++++++++++++++++---------------- quick_tour/the_controller.rst | 143 +++++++++---------- quick_tour/the_view.rst | 133 +++++++++--------- 4 files changed, 332 insertions(+), 308 deletions(-) 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 From 3c9e7382db5464e8a73f6f3bbeca7c9e6e2d22ad Mon Sep 17 00:00:00 2001 From: Jovan Perovic Date: Sun, 19 Apr 2015 13:26:52 +0200 Subject: [PATCH 13/17] Fixed inconsistency All examples but "Annotation" use parameter named "username" whereas it uses parameter "name". --- cookbook/routing/slash_in_parameter.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/routing/slash_in_parameter.rst b/cookbook/routing/slash_in_parameter.rst index 6da1fbc61ee..9a2801705cd 100644 --- a/cookbook/routing/slash_in_parameter.rst +++ b/cookbook/routing/slash_in_parameter.rst @@ -31,9 +31,9 @@ a more permissive regex path. class DemoController { /** - * @Route("/hello/{name}", name="_hello", requirements={"name"=".+"}) + * @Route("/hello/{username}", name="_hello", requirements={"username"=".+"}) */ - public function helloAction($name) + public function helloAction($username) { // ... } From 249295248a090c83e5ac031b5860d55502d71932 Mon Sep 17 00:00:00 2001 From: Marichez Pierre Date: Mon, 20 Apr 2015 15:42:28 +0200 Subject: [PATCH 14/17] Fix priority range values for event listeners. --- cookbook/service_container/event_listener.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 59fb5978e4c..b1640b490fa 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -96,9 +96,8 @@ using a special "tag": .. note:: There is an additional tag option ``priority`` that is optional and defaults - to 0. This value can be from -255 to 255, and the listeners will be executed - in the order of their priority (highest to lowest). This is useful when - you need to guarantee that one listener is executed before another. + to 0. The listeners will be executed in the order of their priority (highest to lowest). + This is useful when you need to guarantee that one listener is executed before another. Request Events, Checking Types ------------------------------ From f7c84cad02a0d2e94a03b8f08be6eea4c460fe02 Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 22 Apr 2015 00:35:09 +0000 Subject: [PATCH 15/17] added missing tab --- cookbook/serializer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/serializer.rst b/cookbook/serializer.rst index 4c658d90aa6..eedaf349fc6 100644 --- a/cookbook/serializer.rst +++ b/cookbook/serializer.rst @@ -77,7 +77,7 @@ Here is an example on how to load the # app/config/services.yml services: get_set_method_normalizer: - class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer + class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer tags: - { name: serializer.normalizer } From 6cb591ee0fe17adc90e9bc08042040533d32240f Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Wed, 22 Apr 2015 23:31:43 +0200 Subject: [PATCH 16/17] [Cookbook][Security] Replace deprecated csrf_provider service --- cookbook/security/csrf_in_login_form.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/cookbook/security/csrf_in_login_form.rst b/cookbook/security/csrf_in_login_form.rst index d957a2585b5..77e009b13e1 100644 --- a/cookbook/security/csrf_in_login_form.rst +++ b/cookbook/security/csrf_in_login_form.rst @@ -18,7 +18,7 @@ Configuring CSRF Protection First, configure the Security component so it can use CSRF protection. The Security component needs a CSRF token provider. You can set this to use the default -provider available in the Form component: +provider available in the Security component: .. configuration-block:: @@ -31,7 +31,7 @@ provider available in the Form component: # ... form_login: # ... - csrf_provider: form.csrf_provider + csrf_provider: security.csrf.token_manager .. code-block:: xml @@ -46,7 +46,7 @@ provider available in the Form component: - + @@ -60,12 +60,17 @@ provider available in the Form component: // ... 'form_login' => array( // ... - 'csrf_provider' => 'form.csrf_provider', + 'csrf_provider' => 'security.csrf.token_manager', ) ) ) )); +.. versionadded:: 2.4 + The ``security.csrf.token_manager`` service was introduced in Symfony 2.4. + Prior to Symfony 2.4, you can use the ``form.csrf_provider`` service + available in the Form component. + The Security component can be configured further, but this is all information it needs to be able to use CSRF in the login form. From 4eabb4726348483596e97e1788ac21691132002d Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 26 Apr 2015 23:46:48 +0200 Subject: [PATCH 17/17] [#5206] Removed versionadded directives --- cookbook/security/csrf_in_login_form.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/cookbook/security/csrf_in_login_form.rst b/cookbook/security/csrf_in_login_form.rst index 77e009b13e1..0e14196db02 100644 --- a/cookbook/security/csrf_in_login_form.rst +++ b/cookbook/security/csrf_in_login_form.rst @@ -66,11 +66,6 @@ provider available in the Security component: ) )); -.. versionadded:: 2.4 - The ``security.csrf.token_manager`` service was introduced in Symfony 2.4. - Prior to Symfony 2.4, you can use the ``form.csrf_provider`` service - available in the Form component. - The Security component can be configured further, but this is all information it needs to be able to use CSRF in the login form.