Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

.platform.app.yaml

@@ -0,0 +1,55 @@
+# This file describes an application. You can have multiple applications
+# in the same project.
+
+# The name of this app. Must be unique within a project.
+name: symfonydocs
+
+# The toolstack used to build the application.
+type: "php"
+
+build:
+    flavor: "composer"
+
+# The configuration of app when it is exposed to the web.
+web:
+    # The public directory of the app, relative to its root.
+    document_root: "/_build/html"
+    index_files:
+      - index.html
+    whitelist:
+      - \.html$
+      - \.txt$
+
+      # CSS and Javascript.
+      - \.css$
+      - \.js$
+      - \.hbs$
+
+      # image/* types.
+      - \.gif$
+      - \.png$
+      - \.ico$
+      - \.svgz?$
+
+      # fonts types.
+      - \.ttf$
+      - \.eot$
+      - \.woff$
+      - \.otf$
+
+      # robots.txt.
+      - /robots\.txt$
+
+# The size of the persistent disk of the application (in MB).
+disk: 512
+
+# Build time dependencies.
+dependencies:
+  python:
+    sphinx: ">=1"
+
+# The hooks that will be performed when the package is deployed.
+hooks:
+    build: |
+      pip install git+https://github.com/fabpot/sphinx-php.git
+      make html

.platform/routes.yaml

@@ -0,0 +1,16 @@
+http://www.{default}/:
+  to: http://{default}/
+  type: redirect
+http://{default}/:
+  cache:
+    cookies:
+    - '*'
+    default_ttl: 0
+    enabled: true
+    headers:
+    - Accept
+    - Accept-Language
+  ssi:
+    enabled: false
+  type: upstream
+  upstream: symfonydocs:php

.platform/services.yaml

@@ -0,0 +1 @@
+# Keeping this file empty to not deploy unused services.

.travis.yml

@@ -1,16 +1,18 @@
 language: python
 
-python:
-    - "2.7"
+python: "2.7"
 
 sudo: false
 
-install: 
-    - "pip install -q -r requirements.txt --use-mirrors"
+cache:
+    directories:
+        - $HOME/.cache/pip
+        - _build
+
+install: pip install sphinx==1.1.3
 
 script: sphinx-build -nW -b html -d _build/doctrees . _build/html
 
 branches:
   except:
     - github-comments
-

README.markdown

@@ -14,3 +14,8 @@ Contributing
 We love contributors! For more information on how you can contribute to the
 Symfony documentation, please read
 [Contributing to the Documentation](https://symfony.com/doc/current/contributing/documentation/overview.html)
+
+Platform.sh
+-----------
+
+Pull requests are automatically built by [Platform.sh](https://platform.sh).

book/forms.rst

@@ -1145,6 +1145,8 @@ the choice is ultimately up to you.
 
         $form->get('dueDate')->setData(new \DateTime());
 
+.. _form-as-services:
+
 Defining your Forms as Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

book/http_fundamentals.rst

@@ -96,9 +96,11 @@ delete a specific blog entry, for example:
 
 .. note::
 
-    There are actually nine HTTP methods defined by the HTTP specification,
-    but many of them are not widely used or supported. In reality, many modern
-    browsers don't even support the ``PUT`` and ``DELETE`` methods.
+    There are actually nine HTTP methods (also known as verbs) defined by
+    the HTTP specification, but many of them are not widely used or supported.
+    In reality, many modern browsers only support ``POST`` and ``GET`` in 
+    HTML forms. Various others are however supported in XMLHttpRequests,
+    as well as by Symfony's router.  
 
 In addition to the first line, an HTTP request invariably contains other
 lines of information called request headers. The headers can supply a wide

book/installation.rst

@@ -127,7 +127,7 @@ based on `Composer`_.
 
 Composer is the dependency manager used by modern PHP applications and it can
 also be used to create new applications based on the Symfony Framework. If you
-don't have installed it globally, start by reading the next section.
+don't have it installed globally, start by reading the next section.
 
 Installing Composer Globally
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

book/routing.rst

@@ -830,36 +830,36 @@ be accomplished with the following route configuration:
         class MainController extends Controller
         {
             /**
-             * @Route("/contact")
+             * @Route("/news")
              * @Method("GET")
              */
-            public function contactAction()
+            public function newsAction()
             {
-                // ... display contact form
+                // ... display your news
             }
 
             /**
              * @Route("/contact")
-             * @Method("POST")
+             * @Method({"GET", "POST"})
              */
-            public function processContactAction()
+            public function contactFormAction()
             {
-                // ... process contact form
+                // ... display and process a contact form
             }
         }
 
     .. code-block:: yaml
 
         # app/config/routing.yml
-        contact:
-            path:     /contact
-            defaults: { _controller: AppBundle:Main:contact }
+        news:
+            path:     /news
+            defaults: { _controller: AppBundle:Main:news }
             methods:  [GET]
 
-        contact_process:
+        contact_form:
             path:     /contact
-            defaults: { _controller: AppBundle:Main:processContact }
-            methods:  [POST]
+            defaults: { _controller: AppBundle:Main:contactForm }
+            methods:  [GET, POST]
 
     .. code-block:: xml
 
@@ -870,12 +870,12 @@ be accomplished with the following route configuration:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="contact" path="/contact" methods="GET">
-                <default key="_controller">AppBundle:Main:contact</default>
+            <route id="news" path="/news" methods="GET">
+                <default key="_controller">AppBundle:Main:news</default>
             </route>
 
-            <route id="contact_process" path="/contact" methods="POST">
-                <default key="_controller">AppBundle:Main:processContact</default>
+            <route id="contact_form" path="/contact" methods="GET|POST">
+                <default key="_controller">AppBundle:Main:contactForm</default>
             </route>
         </routes>
 
@@ -886,13 +886,13 @@ be accomplished with the following route configuration:
         use Symfony\Component\Routing\Route;
 
         $collection = new RouteCollection();
-        $collection->add('contact', new Route('/contact', array(
+        $collection->add('news', new Route('/news', array(
             '_controller' => 'AppBundle:Main:contact',
         ), array(), array(), '', array(), array('GET')));
 
-        $collection->add('contact_process', new Route('/contact', array(
-            '_controller' => 'AppBundle:Main:processContact',
-        ), array(), array(), '', array(), array('POST')));
+        $collection->add('contact_form', new Route('/contact', array(
+            '_controller' => 'AppBundle:Main:contactForm',
+        ), array(), array(), '', array(), array('GET', 'POST')));
 
         return $collection;
 

book/security.rst

@@ -994,10 +994,10 @@ other users. Also, as the admin user, you yourself want to be able to edit
 
 To accomplish this you have 2 options:
 
-* :doc:`Voters </cookbook/security/voters_data_permission>` allow you to
-  use business logic (e.g. the user can edit this post because they were
-  the creator) to determine access. You'll probably want this option - it's
-  flexible enough to solve the above situation.
+* :doc:`Voters </cookbook/security/voters>` allow you to write own business logic
+  (e.g. the user can edit this post because they were the creator) to determine
+  access. You'll probably want this option - it's flexible enough to solve the
+  above situation.
 
 * :doc:`ACLs </cookbook/security/acl>` allow you to create a database structure
   where you can assign *any* arbitrary user *any* access (e.g. EDIT, VIEW)
@@ -1378,7 +1378,7 @@ Learn More from the Cookbook
 
 * :doc:`Forcing HTTP/HTTPS </cookbook/security/force_https>`
 * :doc:`Impersonating a User </cookbook/security/impersonating_user>`
-* :doc:`/cookbook/security/voters_data_permission`
+* :doc:`/cookbook/security/voters`
 * :doc:`Access Control Lists (ACLs) </cookbook/security/acl>`
 * :doc:`/cookbook/security/remember_me`
 * :doc:`/cookbook/security/multiple_user_providers`

components/console/introduction.rst

@@ -175,22 +175,18 @@ Verbosity Levels
    The ``VERBOSITY_VERY_VERBOSE`` and ``VERBOSITY_DEBUG`` constants were introduced
    in version 2.3
 
-The console has 5 levels of verbosity. These are defined in the
+The console has five verbosity levels. These are defined in the
 :class:`Symfony\\Component\\Console\\Output\\OutputInterface`:
 
-=======================================  ==================================
-Mode                                     Value
-=======================================  ==================================
-OutputInterface::VERBOSITY_QUIET         Do not output any messages
-OutputInterface::VERBOSITY_NORMAL        The default verbosity level
-OutputInterface::VERBOSITY_VERBOSE       Increased verbosity of messages
-OutputInterface::VERBOSITY_VERY_VERBOSE  Informative non essential messages
-OutputInterface::VERBOSITY_DEBUG         Debug messages
-=======================================  ==================================
-
-You can specify the quiet verbosity level with the ``--quiet`` or ``-q``
-option. The ``--verbose`` or ``-v`` option is used when you want an increased
-level of verbosity.
+===========================================  ==================================  =====================
+Value                                        Meaning                             Console option
+===========================================  ==================================  =====================
+``OutputInterface::VERBOSITY_QUIET``         Do not output any messages          ``-q`` or ``--quiet``
+``OutputInterface::VERBOSITY_NORMAL``        The default verbosity level         (none)
+``OutputInterface::VERBOSITY_VERBOSE``       Increased verbosity of messages     ``-v``
+``OutputInterface::VERBOSITY_VERY_VERBOSE``  Informative non essential messages  ``-vv``
+``OutputInterface::VERBOSITY_DEBUG``         Debug messages                      ``-vvv``
+===========================================  ==================================  =====================
 
 .. tip::
 
@@ -223,6 +219,13 @@ verbosity levels::
         // ...
     }
 
+.. note::
+
+    These semantic methods are defined in the ``OutputInterface`` starting from
+    Symfony 3.0. In previous Symfony versions they are defined in the different
+    implementations of the interface (e.g. :class:`Symfony\\Component\\Console\\Output\\Output`)
+    in order to keep backwards compatibility.
+
 When the quiet level is used, all output is suppressed as the default
 :method:`Symfony\\Component\\Console\\Output\\Output::write` method returns
 without actually printing.
@@ -477,6 +480,8 @@ method::
     You can also test a whole console application by using
     :class:`Symfony\\Component\\Console\\Tester\\ApplicationTester`.
 
+.. _calling-existing-command:
+
 Calling an Existing Command
 ---------------------------
 
@@ -506,16 +511,27 @@ Calling a command from another one is straightforward::
     }
 
 First, you :method:`Symfony\\Component\\Console\\Application::find` the
-command you want to execute by passing the command name.
-
-Then, you need to create a new
-:class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the arguments and
-options you want to pass to the command.
+command you want to execute by passing the command name. Then, you need to create
+a new :class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the arguments
+and options you want to pass to the command.
 
 Eventually, calling the ``run()`` method actually executes the command and
 returns the returned code from the command (return value from command's
 ``execute()`` method).
 
+.. tip::
+
+    If you want to suppress the output of the executed command, pass a
+    :class:`Symfony\\Component\\Console\\Output\\NullOutput` as the second
+    argument to ``$command->execute()``.
+
+.. caution::
+
+    Note that all the commands will run in the same process and some of Symfony's
+    built-in commands may not work well this way. For instance, the ``cache:clear``
+    and ``cache:warmup`` commands change some class definitions, so running
+    something after them is likely to break.
+
 .. note::
 
     Most of the time, calling a command from code that is not executed on the

components/http_kernel/introduction.rst

@@ -692,7 +692,7 @@ can be used to check if the current request is a "master" or "sub" request.
 For example, a listener that only needs to act on the master request may
 look like this::
 
-    use Symfony\Component\HttpKernel\HttpKernelInterface;
+    use Symfony\Component\HttpKernel\Event\GetResponseEvent;
     // ...
 
     public function onKernelRequest(GetResponseEvent $event)

components/security/secure_tools.rst

@@ -50,11 +50,21 @@ to work correctly. Just pass a file name to enable it::
     use Symfony\Component\Security\Core\Util\SecureRandom;
 
     $generator = new SecureRandom('/some/path/to/store/the/seed.txt');
+
     $random = $generator->nextBytes(10);
+    $hashedRandom = md5($random); // see tip below
 
 .. note::
 
-    If you're using the Symfony Framework, you can access a secure random
-    instance directly from the container: its name is ``security.secure_random``.
+    If you're using the Symfony Framework, you can get a secure random number
+    generator via the ``security.secure_random`` service.
+
+.. tip::
+
+    The ``nextBytes()`` method returns a binary string which may contain the
+    ``\0`` character. This can cause trouble in several common scenarios, such
+    as storing this value in a database or including it as part of the URL. The
+    solution is to hash the value returned by ``nextBytes()`` (to do that, you
+    can use a simple ``md5()`` PHP function).
 
 .. _`Timing attack`: http://en.wikipedia.org/wiki/Timing_attack