Merge branch '2.1' into 2.2

weaverryan · weaverryan · commit 28b09042b6c6 · 2013-05-05T21:52:27.000-04:00
diff --git a/book/controller.rst b/book/controller.rst
@@ -476,7 +476,7 @@ value to each variable.
 
     Like other base ``Controller`` methods, the ``forward`` method is just
     a shortcut for core Symfony2 functionality. A forward can be accomplished
-    directly via the ``http_kernel`` service. A forward returns a ``Response``
+    directly via the ``http_kernel`` service and returns a ``Response``
     object::
 
         $httpKernel = $this->container->get('http_kernel');
@@ -686,19 +686,23 @@ the ``notice`` message:
 
     .. code-block:: html+jinja
 
-        {% for flashMessage in app.session.flashbag.get('notice') %}
-            <div class="flash-notice">
-                {{ flashMessage }}
-            </div>
-        {% endfor %}
+        {% if app.session.started %}
+            {% for flashMessage in app.session.flashbag.get('notice') %}
+                <div class="flash-notice">
+                    {{ flashMessage }}
+                </div>
+            {% endfor %}
+        {% endif %}
 
     .. code-block:: html+php
 
-        <?php foreach ($view['session']->getFlashBag()->get('notice') as $message): ?>
-            <div class="flash-notice">
-                <?php echo "<div class='flash-error'>$message</div>" ?>
-            </div>
-        <?php endforeach; ?>
+        <?php if ($view['session']->isStarted()): ?>
+            <?php foreach ($view['session']->getFlashBag()->get('notice') as $message): ?>
+                <div class="flash-notice">
+                    <?php echo "<div class='flash-error'>$message</div>" ?>
+                </div>
+            <?php endforeach; ?>
+        <?php endif; ?>
 
 By design, flash messages are meant to live for exactly one request (they're
 "gone in a flash"). They're designed to be used across redirects exactly as
diff --git a/book/stable_api.rst b/book/stable_api.rst
@@ -31,6 +31,7 @@ As of Symfony 2.0, the following components have a public tagged API:
 * DependencyInjection
 * DomCrawler
 * EventDispatcher
+* Filesystem (as of Symfony 2.1)
 * Finder
 * HttpFoundation
 * HttpKernel
diff --git a/components/filesystem.rst b/components/filesystem.rst
@@ -51,8 +51,9 @@ endpoint for filesystem operations::
 Mkdir
 ~~~~~
 
-Mkdir creates directory. On posix filesystems, directories are created with a
-default mode value `0777`. You can use the second argument to set your own mode::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir` creates directory.
+On posix filesystems, directories are created with a default mode value
+`0777`. You can use the second argument to set your own mode::
 
     $fs->mkdir('/tmp/photos', 0700);
 
@@ -64,8 +65,8 @@ default mode value `0777`. You can use the second argument to set your own mode:
 Exists
 ~~~~~~
 
-Exists checks for the presence of all files or directories and returns false if a
-file is missing::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::exists` checks for the
+presence of all files or directories and returns false if a file is missing::
 
     // this directory exists, return true
     $fs->exists('/tmp/photos');
@@ -81,9 +82,10 @@ file is missing::
 Copy
 ~~~~
 
-This method is used to copy files. If the target already exists, the file is
-copied only if the source modification date is later than the target. This
-behavior can be overridden by the third boolean argument::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` is used to copy
+files. If the target already exists, the file is copied only if the source
+modification date is later than the target. This behavior can be overridden by
+the third boolean argument::
 
     // works only if image-ICC has been modified after image.jpg
     $fs->copy('image-ICC.jpg', 'image.jpg');
@@ -94,9 +96,9 @@ behavior can be overridden by the third boolean argument::
 Touch
 ~~~~~
 
-Touch sets access and modification time for a file. The current time is used by
-default. You can set your own with the second argument. The third argument is
-the access time::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::touch` sets access and
+modification time for a file. The current time is used by default. You can set
+your own with the second argument. The third argument is the access time::
 
     // set modification time to the current timestamp
     $fs->touch('file.txt');
@@ -113,8 +115,8 @@ the access time::
 Chown
 ~~~~~
 
-Chown is used to change the owner of a file. The third argument is a boolean
-recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` is used to change
+the owner of a file. The third argument is a boolean recursive option::
 
     // set the owner of the lolcat video to www-data
     $fs->chown('lolcat.mp4', 'www-data');
@@ -129,8 +131,8 @@ recursive option::
 Chgrp
 ~~~~~
 
-Chgrp is used to change the group of a file. The third argument is a boolean
-recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` is used to change
+the group of a file. The third argument is a boolean recursive option::
 
     // set the group of the lolcat video to nginx
     $fs->chgrp('lolcat.mp4', 'nginx');
@@ -146,8 +148,8 @@ recursive option::
 Chmod
 ~~~~~
 
-Chmod is used to change the mode of a file. The fourth argument is a boolean
-recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` is used to change
+the mode of a file. The fourth argument is a boolean recursive option::
 
     // set the mode of the video to 0600
     $fs->chmod('video.ogg', 0600);
@@ -162,7 +164,8 @@ recursive option::
 Remove
 ~~~~~~
 
-Remove let's you remove files, symlink, directories easily::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` let's you remove
+files, symlink, directories easily::
 
     $fs->remove(array('symlink', '/path/to/directory', 'activity.log'));
 
@@ -174,7 +177,8 @@ Remove let's you remove files, symlink, directories easily::
 Rename
 ~~~~~~
 
-Rename is used to rename files and directories::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::rename` is used to rename
+files and directories::
 
     //rename a file
     $fs->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg');
@@ -184,8 +188,9 @@ Rename is used to rename files and directories::
 symlink
 ~~~~~~~
 
-Creates a symbolic link from the target to the destination. If the filesystem
-does not support symbolic links, a third boolean argument is available::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::symlink` creates a
+symbolic link from the target to the destination. If the filesystem does not
+support symbolic links, a third boolean argument is available::
 
     // create a symbolic link
     $fs->symlink('/path/to/source', '/path/to/destination');
@@ -196,7 +201,8 @@ does not support symbolic links, a third boolean argument is available::
 makePathRelative
 ~~~~~~~~~~~~~~~~
 
-Return the relative path of a directory given another one::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` returns
+the relative path of a directory given another one::
 
     // returns '../'
     $fs->makePathRelative(
@@ -209,14 +215,16 @@ Return the relative path of a directory given another one::
 mirror
 ~~~~~~
 
-Mirrors a directory::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` mirrors a
+directory::
 
     $fs->mirror('/path/to/source', '/path/to/target');
 
 isAbsolutePath
 ~~~~~~~~~~~~~~
 
-isAbsolutePath returns true if the given path is absolute, false otherwise::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::isAbsolutePath` returns
+``true`` if the given path is absolute, false otherwise::
 
     // return true
     $fs->isAbsolutePath('/tmp');
@@ -236,9 +244,9 @@ thrown.
 
 .. note::
 
-    Prior to version 2.1, :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`
-    returned a boolean and did not throw exceptions. As of 2.1, a
-    :class:`Symfony\\Component\\Filesystem\\Exception\\IOException` is
-    thrown if a directory creation fails.
+    Prior to version 2.1, ``mkdir`` returned a boolean and did not throw
+    exceptions. As of 2.1, a
+    :class:`Symfony\\Component\\Filesystem\\Exception\\IOException` is thrown
+    if a directory creation fails.
 
 .. _`Packagist`: https://packagist.org/packages/symfony/filesystem
diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst
@@ -333,3 +333,16 @@ Compact method to process display all flashes at once::
             echo "<div class='flash-$type'>$message</div>\n";
         }
     }
+
+.. caution::
+
+    As flash messages use a session to store the messages from one request to
+    the next one, a session will be automatically started when you read the
+    flash messages even if none already exists. To avoid that default
+    behavior, test if there is an existing session first::
+
+        if ($session->isStarted()) {
+            foreach ($session->getFlashBag()->get('warning', array()) as $message) {
+                echo "<div class='flash-warning'>$message</div>";
+            }
+        }
diff --git a/components/http_kernel/introduction.rst b/components/http_kernel/introduction.rst
@@ -614,7 +614,7 @@ a built-in ControllerResolver that can be used to create a working example::
             '_controller' => function (Request $request) {
                 return new Response(sprintf("Hello %s", $request->get('name')));
             }
-        ),
+        )
     ));
 
     $request = Request::createFromGlobals();
diff --git a/components/security/authentication.rst b/components/security/authentication.rst
@@ -119,7 +119,7 @@ from the user data storage, hash the password the user has just provided
 the given password is valid.
 
 This functionality is offered by the :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\DaoAuthenticationProvider`.
-It fetches the user's data from a :class:`Symfony\\Component\\Security\\Core\\User\\UserProviderInterface``,
+It fetches the user's data from a :class:`Symfony\\Component\\Security\\Core\\User\\UserProviderInterface`,
 uses a :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`
 to create a hash of the password and returns an authenticated token if the
 password was valid::
diff --git a/cookbook/security/target_path.rst b/cookbook/security/target_path.rst
@@ -62,8 +62,8 @@ Next, create your own ``ExceptionListener``::
                 return;
             }
 
-            $request->getSession()->set('_security.main.target_path', $request->getUri());
+            parent::setTargetPath($request);
         }
     }
 
-Add as much or few logic here as required for your scenario!
+Add as much or few logic here as required for your scenario!
diff --git a/quick_tour/the_controller.rst b/quick_tour/the_controller.rst
@@ -141,9 +141,11 @@ next request::
 
     // display any messages back in the next request (in a template)
 
-    {% for flashMessage in app.session.flashbag.get('notice') %}
-        <div>{{ flashMessage }}</div>
-    {% endfor %}
+    {% if app.session.started %}
+        {% for flashMessage in app.session.flashbag.get('notice') %}
+            <div>{{ flashMessage }}</div>
+        {% endfor %}
+    {% endif %}
 
 This is useful when you need to set a success message before redirecting
 the user to another page (which will then show the message). Please note that
diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
@@ -31,6 +31,10 @@ may also be tags in other bundles you use that aren't listed here.
 +-----------------------------------+---------------------------------------------------------------------------+
 | `data_collector`_                 | Create a class that collects custom data for the profiler                 |
 +-----------------------------------+---------------------------------------------------------------------------+
+| `doctrine.event_listener`_        | Add a Doctrine event listener                                             |
++-----------------------------------+---------------------------------------------------------------------------+
+| `doctrine.event_subscriber`_      | Add a Doctrine event subscriber                                           |
++-----------------------------------+---------------------------------------------------------------------------+
 | `form.type`_                      | Create a custom form field type                                           |
 +-----------------------------------+---------------------------------------------------------------------------+
 | `form.type_extension`_            | Create a custom "form extension"                                          |
@@ -235,6 +239,22 @@ data_collector
 For details on creating your own custom data collection, read the cookbook
 article: :doc:`/cookbook/profiler/data_collector`.
 
+doctrine.event_listener
+--------------
+
+**Purpose**: Add a Doctrine event listener
+
+For details on creating Doctrine event listeners, read the cookbook article:
+:doc:`/cookbook/doctrine/event_listeners_subscribers`.
+
+doctrine.event_subscriber
+--------------
+
+**Purpose**: Add a Doctrine event subscriber
+
+For details on creating Doctrine event subscribers, read the cookbook article:
+:doc:`/cookbook/doctrine/event_listeners_subscribers`.
+
 .. _dic-tags-form-type:
 
 form.type

Original file line number	Diff line number	Diff line change
`@@ -614,7 +614,7 @@ a built-in ControllerResolver that can be used to create a working example::`
`614`	`614`	`'_controller' => function (Request $request) {`
`615`	`615`	`return new Response(sprintf("Hello %s", $request->get('name')));`
`616`	`616`	`}`
`617`		`- ),`
	`617`	`+ )`
`618`	`618`	`));`
`619`	`619`
`620`	`620`	`$request = Request::createFromGlobals();`
Original file line number	Diff line number	Diff line change
@@ -62,8 +62,8 @@ Next, create your own ``ExceptionListener``::
`62`	`62`	`return;`
`63`	`63`	`}`
`64`	`64`
`65`		`- $request->getSession()->set('_security.main.target_path', $request->getUri());`
	`65`	`+ parent::setTargetPath($request);`
`66`	`66`	`}`
`67`	`67`	`}`
`68`	`68`
`69`		`-Add as much or few logic here as required for your scenario!`
	`69`	`+Add as much or few logic here as required for your scenario!`