Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

best_practices/business-logic.rst

@@ -15,7 +15,7 @@ Inside here, you can create whatever directories you want to organize things:
 
 .. code-block:: text
 
-    symfony2-project/
+    symfony-project/
     ├─ app/
     ├─ src/
     │  └─ AppBundle/
@@ -35,7 +35,7 @@ and put things there:
 
 .. code-block:: text
 
-    symfony2-project/
+    symfony-project/
     ├─ app/
     ├─ src/
     │  ├─ Acme/
@@ -180,7 +180,7 @@ The three entities defined by our sample blog application are a good example:
 
 .. code-block:: text
 
-    symfony2-project/
+    symfony-project/
     ├─ ...
     └─ src/
        └─ AppBundle/

best_practices/controllers.rst

@@ -85,10 +85,10 @@ it more difficult to know which template is being rendered. It also makes
 it less obvious to beginners that a controller should always return a Response
 object (unless you're using a view layer).
 
-How the Controller Looks
-------------------------
+What does the Controller look like
+----------------------------------
 
-Considering all this, here is an example of how the controller should look
+Considering all this, here is an example of what the controller should look like
 for the homepage of our app:
 
 .. code-block:: php

components/cache/cache_pools.rst

@@ -169,7 +169,7 @@ is ``getItem($key)``, which returns the cache item identified by the given key::
 
     use Symfony\Component\Cache\Adapter\FilesystemAdapter;
 
-    $cache = new FilesystemAdapter('app.cache')
+    $cache = new FilesystemAdapter('app.cache');
     $latestNews = $cache->getItem('latest_news');
 
 If no item is defined for the given key, the method doesn't return a ``null``

components/console/single_command_tool.rst

@@ -6,68 +6,51 @@ Building a single Command Application
 
 When building a command line tool, you may not need to provide several commands.
 In such case, having to pass the command name each time is tedious. Fortunately,
-it is possible to remove this need by extending the application::
-
-    namespace Acme\Tool;
-
-    use Symfony\Component\Console\Application;
-    use Symfony\Component\Console\Input\InputInterface;
-
-    class MyApplication extends Application
-    {
-        /**
-         * Gets the name of the command based on input.
-         *
-         * @param InputInterface $input The input interface
-         *
-         * @return string The command name
-         */
-        protected function getCommandName(InputInterface $input)
-        {
-            // This should return the name of your command.
-            return 'my_command';
-        }
-
-        /**
-         * Gets the default commands that should always be available.
-         *
-         * @return array An array of default Command instances
-         */
-        protected function getDefaultCommands()
-        {
-            // Keep the core default commands to have the HelpCommand
-            // which is used when using the --help option
-            $defaultCommands = parent::getDefaultCommands();
-
-            $defaultCommands[] = new MyCommand();
-
-            return $defaultCommands;
-        }
-
-        /**
-         * Overridden so that the application doesn't expect the command
-         * name to be the first argument.
-         */
-        public function getDefinition()
-        {
-            $inputDefinition = parent::getDefinition();
-            // clear out the normal first argument, which is the command name
-            $inputDefinition->setArguments();
-
-            return $inputDefinition;
-        }
-    }
-
-When calling your console script, the command ``MyCommand`` will then always
-be used, without having to pass its name.
-
-You can also simplify how you execute the application::
-
-    #!/usr/bin/env php
-    <?php
-    // command.php
-
-    use Acme\Tool\MyApplication;
-
-    $application = new MyApplication();
-    $application->run();
+it is possible to remove this need by declaring a single command application::
+
+  #!/usr/bin/env php
+  <?php
+  require __DIR__.'/vendor/autoload.php';
+
+  use Symfony\Component\Console\Application;
+  use Symfony\Component\Console\Input\InputArgument;
+  use Symfony\Component\Console\Input\InputInterface;
+  use Symfony\Component\Console\Input\InputOption;
+  use Symfony\Component\Console\Output\OutputInterface;
+
+  (new Application('echo', '1.0.0'))
+    ->register('echo')
+        ->addArgument('foo', InputArgument::OPTIONAL, 'The directory')
+        ->addOption('bar', null, InputOption::VALUE_REQUIRED)
+        ->setCode(function(InputInterface $input, OutputInterface $output) {
+            // output arguments and options
+        })
+    ->getApplication()
+    ->setDefaultCommand('echo', true) // Single command application
+    ->run();
+
+The method :method:`Symfony\\Component\\Console\\Application::setDefaultCommand`
+accepts a boolean as second parameter. If true, the command ``echo`` will then
+always be used, without having to pass its name.
+
+Of course, you can still register a command as usual::
+
+  #!/usr/bin/env php
+  <?php
+  require __DIR__.'/vendor/autoload.php';
+
+  use Symfony\Component\Console\Application;
+  use Symfony\Component\Console\Input\InputArgument;
+  use Symfony\Component\Console\Input\InputInterface;
+  use Symfony\Component\Console\Input\InputOption;
+  use Symfony\Component\Console\Output\OutputInterface;
+
+  use Acme\Command\DefaultCommand;
+
+  $application = new Application('echo', '1.0.0');
+  $command = new DefaultCommand();
+
+  $application->add($command);
+
+  $application->setDefaultCommand($command->getName(), true);
+  $application->run();

components/expression_language.rst

@@ -21,7 +21,7 @@ How can the Expression Engine Help Me?
 --------------------------------------
 
 The purpose of the component is to allow users to use expressions inside
-configuration for more complex logic. For some examples, the Symfony2 Framework
+configuration for more complex logic. For some examples, the Symfony Framework
 uses expressions in security, for validation rules and in route matching.
 
 Besides using the component in the framework itself, the ExpressionLanguage

components/filesystem.rst

@@ -60,6 +60,10 @@ On POSIX filesystems, directories are created with a default mode value
     You can pass an array or any :phpclass:`Traversable` object as the first
     argument.
 
+.. note::
+
+    This function ignores already existing directories.
+
 exists
 ~~~~~~
 

components/routing.rst

@@ -346,6 +346,185 @@ automatically in the background if you want to use it. A basic example of the
     are saved in the ``cache_dir``. This means your script must have write
     permissions for that location.
 
+Unicode Routing Support
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2
+    UTF-8 support for route paths and requirements was introduced in
+    Symfony 3.2.
+
+The Routing component supports UTF-8 characters in route paths and requirements.
+Thanks to the ``utf8`` route option, you can make Symfony match and generate
+routes with UTF-8 characters:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/AppBundle/Controller/DefaultController.php
+        namespace AppBundle\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+        class DefaultController extends Controller
+        {
+            /**
+             *
+             * @Route("/category/{name}", name="route1", options={"utf8": true})
+             *
+             */
+            public function categoryAction()
+            {
+                // ...
+            }
+
+    .. code-block:: yaml
+
+        # app/config/routing.yml
+        route1:
+            path:     /category/{name}
+            defaults: { _controller: 'AppBundle:Default:category' }
+            options:
+                utf8: true
+
+    .. code-block:: xml
+
+        <!-- app/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="route1" path="/category/{name}">
+                <default key="_controller">AppBundle:Default:category</default>
+                <option key="utf8">true</option>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // app/config/routing.php
+        use Symfony\Component\Routing\RouteCollection;
+        use Symfony\Component\Routing\Route;
+
+        $collection = new RouteCollection();
+        $collection->add('route1', new Route('/category/{name}',
+            array(
+                '_controller' => 'AppBundle:Default:category',
+            ),
+            array(),
+            array(
+                'utf8' => true,
+            )
+        );
+
+        // ...
+
+        return $collection;
+
+
+In this route, the ``utf8`` option set to ``true`` makes Symfony consider the
+``.`` requirement to match any UTF-8 characters instead of just a single
+byte character. This means that so the following URLs would match:
+``/category/日本語``, ``/category/فارسی``, ``/category/한국어``, etc. In case you
+are wondering, this option also allows to include and match emojis in URLs.
+
+You can also include UTF-8 strings as routing requirements:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/AppBundle/Controller/DefaultController.php
+        namespace AppBundle\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+        class DefaultController extends Controller
+        {
+            /**
+                *
+                * @Route(
+                *     "/category/{name}",
+                *     name="route2",
+                *     requirements={"default"="한국어"},
+                *     options={"utf8": true}
+                * )
+                *
+                */
+            public function defaultAction()
+            {
+                // ...
+            }
+
+    .. code-block:: yaml
+
+        # app/config/routing.yml
+        route2:
+            path:     /default/{default}
+            defaults: { _controller: 'AppBundle:Default:default' }
+            requirements:
+                default: "한국어"
+            options:
+                utf8: true
+
+    .. code-block:: xml
+
+        <!-- app/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="route2" path="/default/{default}">
+                <default key="_controller">AppBundle:Default:default</default>
+                <requirement key="default">한국어</requirement>
+                <option key="utf8">true</option>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // app/config/routing.php
+        use Symfony\Component\Routing\RouteCollection;
+        use Symfony\Component\Routing\Route;
+
+        $collection = new RouteCollection();
+        $collection->add('route2', new Route('/default/{default}',
+            array(
+                '_controller' => 'AppBundle:Default:default',
+            ),
+            array(
+                'default' => '한국어',
+            ),
+            array(
+                'utf8' => true,
+            )
+        );
+
+        // ...
+
+        return $collection;
+    
+.. tip::
+
+    In addition to UTF-8 characters, the Routing component also supports all
+    the `PCRE Unicode properties`_, which are escape sequences that match
+    generic character types. For example, ``\p{Lu}`` matches any uppercase
+    character in any language, ``\p{Greek}`` matches any Greek character,
+    ``\P{Han}`` matches any character not included in the Chinese Han script.
+
+.. note::
+
+    In Symfony 3.2 there is no need to set the ``utf8`` option explicitly. As
+    soon as Symfony finds a UTF-8 character in the route path or requirements,
+    it will turn the UTF-8 support automatically. However, this behaviour is
+    deprecated and setting the option will be required in Symfony 4.0.
+
 Learn more
 ----------
 
@@ -360,3 +539,4 @@ Learn more
     /configuration/apache_router
 
 .. _Packagist: https://packagist.org/packages/symfony/routing
+.. _PCRE Unicode properties: http://php.net/manual/en/regexp.reference.unicode.php

components/yaml/yaml_format.rst

@@ -158,7 +158,7 @@ YAML uses the ISO-8601 standard to express dates:
 
 .. code-block:: yaml
 
-    2001-12-14t21:59:43.10-05:00
+    2001-12-14T21:59:43.10-05:00
 
 .. code-block:: yaml