Merge branch '2.1' into 2.2

weaverryan · weaverryan · commit 8e5cacaa5b46 · 2013-08-17T13:07:44.000-04:00
Conflicts:
	components/event_dispatcher/introduction.rst
	cookbook/symfony1.rst
diff --git a/components/event_dispatcher/immutable_dispatcher.rst b/components/event_dispatcher/immutable_dispatcher.rst
@@ -0,0 +1,41 @@
+.. index::
+    single: Event Dispatcher; Immutable
+
+The Immutable Event Dispatcher
+==============================
+
+.. versionadded:: 2.1
+    This feature was added in Symfony 2.1.
+
+The :class:`Symfony\\Component\\EventDispatcher\\ImmutableEventDispatcher` is
+a locked or frozen event dispatcher. The dispatcher cannot register new
+listeners or subscribers.
+
+The ``ImmutableEventDispatcher`` takes another event dispatcher with all the
+listeners and subscribers. The immutable dispatcher is just a proxy of this
+original dispatcher.
+
+To use it, first create a normal dispatcher (``EventDispatcher`` or
+``ContainerAwareEventDispatcher``) and register some listeners or
+subscribers::
+
+    use Symfony\Component\EventDispatcher\EventDispatcher;
+
+    $dispatcher = new EventDispatcher();
+    $dispatcher->addListener('foo.action', function ($event) {
+        // ...
+    });
+
+    // ...
+
+Now, inject that into an ``ImmutableEventDispatcher``::
+
+    use Symfony\Component\EventDispatcher\ImmutableEventDispatcher;
+    // ...
+
+    $immutableDispatcher = new ImmutableEventDispatcher($dispatcher);
+
+You'll need to use this new dispatcher in your project.
+
+If you are trying to execute one of the methods which modifies the dispatcher
+(e.g. ``addListener``), a ``BadMethodCallException`` is thrown.
diff --git a/components/event_dispatcher/index.rst b/components/event_dispatcher/index.rst
@@ -5,5 +5,6 @@ Event Dispatcher
     :maxdepth: 2
 
     introduction
-    generic_event
     container_aware_dispatcher
+    generic_event
+    immutable_dispatcher
diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst
@@ -597,6 +597,15 @@ part of the listener's processing logic::
         }
     }
 
+Other Dispatchers
+-----------------
+
+Besides the commonly used ``EventDispatcher``, the component comes with 2
+other dispatchers:
+
+* :doc:`/components/event_dispatcher/container_aware_dispatcher`
+* :doc:`/components/event_dispatcher/immutable_dispatcher`
+
 .. _Mediator: http://en.wikipedia.org/wiki/Mediator_pattern
 .. _Closures: http://php.net/manual/en/functions.anonymous.php
 .. _PHP callable: http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback
diff --git a/components/map.rst.inc b/components/map.rst.inc
@@ -45,6 +45,7 @@
   * :doc:`/components/event_dispatcher/introduction`
   * :doc:`/components/event_dispatcher/container_aware_dispatcher`
   * :doc:`/components/event_dispatcher/generic_event`
+  * :doc:`/components/event_dispatcher/immutable_dispatcher`
 
 * **Filesystem**
 
diff --git a/cookbook/symfony1.rst b/cookbook/symfony1.rst
@@ -119,7 +119,7 @@ were added or moved.
 In Symfony2, a tool named `Composer`_ handles this process.
 The idea behind the autoloader is simple: the name of your class (including
 the namespace) must match up with the path to the file containing that class.
-Take the ``FrameworkExtraBundle`` from the Symfony2 Standard Edition as an
+Take the FrameworkExtraBundle from the Symfony2 Standard Edition as an
 example::
 
     namespace Sensio\Bundle\FrameworkExtraBundle;
@@ -134,26 +134,30 @@ example::
 
 The file itself lives at
 ``vendor/sensio/framework-extra-bundle/Sensio/Bundle/FrameworkExtraBundle/SensioFrameworkExtraBundle.php``.
-As you can see, the location of the file follows the namespace of the class.
-Specifically, the namespace, ``Sensio\Bundle\FrameworkExtraBundle``, spells out
-the directory that the file should live in
+As you can see, the second part of the path follows the namespace of the
+class. The first part is equal to the package name of the SensioFrameworkExtraBundle.
+
+The namespace, ``Sensio\Bundle\FrameworkExtraBundle``, and package name,
+``sensio/framework-extra-bundle``, spells out the directory that the file
+should live in
 (``vendor/sensio/framework-extra-bundle/Sensio/Bundle/FrameworkExtraBundle/``).
-Composer can then look for the file at this specific place and load it very fast.
+Composer can then look for the file at this specific place and load it very
+fast.
 
 If the file did *not* live at this exact location, you'd receive a
 ``Class "Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle" does not exist.``
-error. In Symfony2, a "class does not exist" means that the suspect class
-namespace and physical location do not match. Basically, Symfony2 is looking
+error. In Symfony2, a "class does not exist" error means that the namespace of
+the class and physical location do not match. Basically, Symfony2 is looking
 in one exact location for that class, but that location doesn't exist (or
 contains a different class). In order for a class to be autoloaded, you
 **never need to clear your cache** in Symfony2.
 
 As mentioned before, for the autoloader to work, it needs to know that the
-``Sensio`` namespace lives in the ``vendor/bundles`` directory and that, for
-example, the ``Doctrine`` namespace lives in the ``vendor/doctrine/orm/lib/``
-directory. This mapping is entirely controlled by Composer. Each
-third-party library you load through composer has their settings defined
-and Composer takes care of everything for you.
+``Sensio`` namespace lives in the ``vendor/sensio/framework-extra-bundle``
+directory and that, for example, the ``Doctrine`` namespace lives in the
+``vendor/doctrine/orm/lib/`` directory. This mapping is entirely controlled by
+Composer. Each third-party library you load through Composer has its
+settings defined and Composer takes care of everything for you.
 
 For this to work, all third-party libraries used by your project must be
 defined in the ``composer.json`` file.
@@ -170,6 +174,11 @@ from specific directories without defining a dependency:
         "psr-0": { "": "src/" }
     }
 
+This means that if a class is not found in the ``vendor`` directory, Composer
+will search in the ``src`` directory before throwing a "class does not exist"
+exception. Read more about configuring the Composer Autoloader in
+`the Composer documentation`_
+
 Using the Console
 -----------------
 
@@ -357,3 +366,4 @@ the chapter titled ":doc:`/book/service_container`".
 
 .. _`Composer`: http://getcomposer.org
 .. _`Symfony2 Standard Edition`: https://github.com/symfony/symfony-standard
+.. _`the Composer documentation`: http://getcomposer.org/doc/04-schema.md#autoload
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -244,7 +244,7 @@ gc_maxlifetime
 .. versionadded:: 2.1
     The ``gc_maxlifetime`` option is new in version 2.1
 
-**type**: ``integer`` **default**: ``14400``
+**type**: ``integer`` **default**: ``1440``
 
 This determines the number of seconds after which data will be seen as "garbage"
 and potentially cleaned up. Garbage collection may occur during session start
diff --git a/reference/constraints/Regex.rst b/reference/constraints/Regex.rst
@@ -7,6 +7,7 @@ Validates that a value matches a regular expression.
 | Applies to     | :ref:`property or method<validation-property-target>`                 |
 +----------------+-----------------------------------------------------------------------+
 | Options        | - `pattern`_                                                          |
+|                | - `htmlPattern`_                                                      |
 |                | - `match`_                                                            |
 |                | - `message`_                                                          |
 +----------------+-----------------------------------------------------------------------+
@@ -173,6 +174,93 @@ does *not* match this regular expression (via the :phpfunction:`preg_match` PHP
 However, if `match`_ is set to false, then validation will fail if the input
 string *does* match this pattern.
 
+htmlPattern
+~~~~~~~~~~~
+
+.. versionadded:: 2.1
+    The ``htmlPattern`` option was added in Symfony 2.1
+
+**type**: ``string|Boolean`` **default**: null
+
+This option specifies the pattern to use in the HTML5 ``pattern`` attribute.
+You usually don't need to specify this option because by default, the constraint
+will convert the pattern given in the `pattern`_ option into an HTML5 compatible
+pattern. This means that the delimiters are removed (e.g. ``/[a-z]+/`` becomes ``[a-z]+``).
+
+However, there are some other incompatibilities between both patterns which
+cannot be fixed by the constraint. For instance, the html5 pattern attribute
+does not support flags. If you have a pattern like ``/[a-z]+/i`` you need to
+specify the html5 compatible pattern in the ``htmlPattern`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/Acme/BlogBundle/Resources/config/validation.yml
+        Acme\BlogBundle\Entity\Author:
+            properties:
+                name:
+                    - Regex:
+                        pattern: "/^[a-z]+$/i"
+                        htmlPattern: "^[a-zA-Z]+$"
+
+    .. code-block:: php-annotations
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+        
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            /**
+             * @Assert\Regex({
+             *     pattern     = "/^[a-z]+$/i",
+             *     htmlPattern = "^[a-zA-Z]+$"
+             * })
+             */
+            protected $name;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/BlogBundle/Resources/config/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="Acme\BlogBundle\Entity\Author">
+                <property name="name">
+                    <constraint name="Regex">
+                        <option name="pattern">/^[a-z]+$/i</option>
+                        <option name="htmlPattern">^[a-zA-Z]+$</option>
+                    </constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+        
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('name', new Assert\Regex(array(
+                    'pattern'     => '/^[a-z]+$/i',
+                    'htmlPattern' => '^[a-zA-Z]+$',
+                )));
+            }
+        }
+
+Setting ``htmlPattern`` to false will disable client side validation.
+
 match
 ~~~~~
 
