Merge branch '2.5'

* 2.5:
  Putting #pull-request-format anchor link back, which we link to in our contrib notes
  Re-adding one more version
  [#4290] Re-adding version back
  Fixing bad link
  Updating library/bundle installation docs to use the new composer require (no version) functionality
  [#4233][#4094] Making validateValue and validate changes
  Minor tweaks and a missing location thanks to xabbuh and WouterJ
  Fixes thanks to @xabbuh
  Adding a section about keeping BC in a re-usable bundle
  Adding details about the 2.4 API as comments
  added a versionadded comment to Callback.rst
  Update custom_contraint.rst to meet the new 2.5 api
  Don't use deprecated functions in Callback.rst
  Update Callback.rst
  Replace addViolationAt (deprecated) by buildViolation

Author: weaverryan

book/validation.rst

@@ -822,9 +822,13 @@ With this configuration, there are three validation groups:
   fields only.
 
 To tell the validator to use a specific group, pass one or more group names
-as the second argument to the ``validate()`` method::
+as the third argument to the ``validate()`` method::
 
-    $errors = $validator->validate($author, array('registration'));
+    // If you're using the new 2.5 validation API (you probably are!)
+    $errors = $validator->validate($author, null, array('registration'));
+
+    // If you're using the old 2.4 validation API
+    // $errors = $validator->validate($author, array('registration'));
 
 If no groups are specified, all constraints that belong in group ``Default``
 will be applied.
@@ -1189,10 +1193,19 @@ it looks like this::
         $emailConstraint->message = 'Invalid email address';
 
         // use the validator to validate the value
+        // If you're using the new 2.5 validation API (you probably are!)
+        $errorList = $this->get('validator')->validate(
+            $email,
+            $emailConstraint
+        );
+
+        // If you're using the old 2.4 validation API
+        /*
         $errorList = $this->get('validator')->validateValue(
             $email,
             $emailConstraint
         );
+        */
 
         if (count($errorList) == 0) {
             // this IS a valid email address, do something
@@ -1206,13 +1219,13 @@ it looks like this::
         // ...
     }
 
-By calling ``validateValue`` on the validator, you can pass in a raw value and
+By calling ``validate`` on the validator, you can pass in a raw value and
 the constraint object that you want to validate that value against. A full
 list of the available constraints - as well as the full class name for each
 constraint - is available in the :doc:`constraints reference </reference/constraints>`
 section .
 
-The ``validateValue`` method returns a :class:`Symfony\\Component\\Validator\\ConstraintViolationList`
+The ``validate`` method returns a :class:`Symfony\\Component\\Validator\\ConstraintViolationList`
 object, which acts just like an array of errors. Each error in the collection
 is a :class:`Symfony\\Component\\Validator\\ConstraintViolation` object,
 which holds the error message on its ``getMessage`` method.

components/dependency_injection/lazy_services.rst

@@ -30,21 +30,19 @@ the `ProxyManager bridge`_:
 
 .. code-block:: bash
 
-    $ php composer.phar require symfony/proxy-manager-bridge:2.3.*
+    $ php composer.phar require symfony/proxy-manager-bridge:~2.3
 
 .. note::
 
     If you're using the full-stack framework, the proxy manager bridge is already
-    included but the actual proxy manager needs to be included. Therefore add
+    included but the actual proxy manager needs to be included. So, run:
 
-    .. code-block:: json
+    .. code-block:: bash
 
-        "require": {
-            "ocramius/proxy-manager": "0.5.*"
-        }
+        $ php composer.phar require ocramius/proxy-manager:~0.5
 
-    to your ``composer.json``. Afterwards compile your container and check
-    to make sure that you get a proxy for your lazy services.
+    Afterwards compile your container and check to make sure that you get
+    a proxy for your lazy services.
 
 Configuration
 -------------

contributing/documentation/overview.rst

@@ -94,6 +94,8 @@ to base your changes on. The **compare repository** should be your forked copy
 of ``symfony-docs`` and the **compare branch** should be ``improve_install_chapter``,
 which is the name of the branch you created and where you made your changes.
 
+.. _pull-request-format:
+
 **Step 8.** The last step is to prepare the **description** of the pull request.
 To ensure that your work is reviewed quickly, please add the following table
 at the beginning of your pull request description:

cookbook/bundles/best_practices.rst

@@ -219,7 +219,7 @@ following standardized instructions in your ``README.md`` file.
     following command to download the latest stable version of this bundle:
 
     ```bash
-    $ composer require <package-name> "~1"
+    $ composer require <package-name>
     ```
 
     This command requires you to have Composer installed globally, as explained
@@ -254,9 +254,6 @@ following standardized instructions in your ``README.md`` file.
     }
     ```
 
-This template assumes that your bundle is in its ``1.x`` version. If not, change
-the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)
-
 Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to
 explain other required installation tasks, such as registering routes or
 dumping assets.
@@ -335,6 +332,48 @@ semantic configuration described in the cookbook.
     If you are defining services, they should also be prefixed with the bundle
     alias.
 
+Custom Validation Constraints
+-----------------------------
+
+Starting with Symfony 2.5, a new Validation API was introduced. In fact,
+there are 3 modes, which the user can configure in their project:
+
+* 2.4: the original 2.4 and earlier validation API;
+* 2.5: the new 2.5 and later validation API;
+* 2.5-BC: the new 2.5 API with a backwards-compatible layer so that the
+  2.4 API still works. This is only available in PHP 5.3.9+.
+
+As a bundle author, you'll want to support *both* API's, since some users
+may still be using the 2.4 API. Specifically, if your bundle adds a violation
+directly to the :class:`Symfony\\Component\\Validator\\Context\\ExecutionContext`
+(e.g. like in a custom validation constraint), you'll need to check for which
+API is being used. The following code, would work for *all* users::
+
+    use Symfony\Component\Validator\ConstraintValidator;
+    use Symfony\Component\Validator\Constraint;
+    use Symfony\Component\Validator\Context\ExecutionContextInterface;
+    // ...
+
+    class ContainsAlphanumericValidator extends ConstraintValidator
+    {
+        public function validate($value, Constraint $constraint)
+        {
+            if ($this->context instanceof ExecutionContextInterface) {
+                // the 2.5 API
+                $this->context->buildViolation($constraint->message)
+                    ->setParameter('%string%', $value)
+                    ->addViolation();
+                );
+            } else {
+                // the 2.4 API
+                $this->context->addViolation(
+                    $constraint->message,
+                    array('%string%' => $value)
+                );
+            }
+        }
+    }
+
 Learn more from the Cookbook
 ----------------------------
 

cookbook/bundles/installation.rst

@@ -5,69 +5,46 @@ How to Install 3rd Party Bundles
 ================================
 
 Most bundles provide their own installation instructions. However, the
-basic steps for installing a bundle are the same.
+basic steps for installing a bundle are the same:
 
-Add Composer Dependencies
--------------------------
+* `A) Add Composer Dependencies`_
+* `B) Enable the Bundle`_
+* `C) Configure the Bundle`_
 
-In Symfony, dependencies are managed with Composer. It's a good idea to learn
-some basics of Composer in `their documentation`_.
+A) Add Composer Dependencies
+----------------------------
 
-Before you can use Composer to install a bundle, you should look for a
-`Packagist`_ package of that bundle. For example, if you search for the popular
-`FOSUserBundle`_ you will find a package called `friendsofsymfony/user-bundle`_.
+Dependencies are managed with Composer, so if Composer is new to you, learn
+some basics in `their documentation`_. This has 2 steps:
 
-.. note::
-
-    Packagist is the main archive for Composer. If you are searching
-    for a bundle, the best thing you can do is check out
-    `KnpBundles`_, it is the unofficial archive of Symfony Bundles. If
-    a bundle contains a ``README`` file, it is displayed there and if it
-    has a Packagist package it shows a link to the package. It's a
-    really useful site to begin searching for bundles.
+1) Find out the Name of the Bundle on Packagist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now that you have the package name, you should determine the version
-you want to use. Usually different versions of a bundle correspond to
-a particular version of Symfony. This information should be in the ``README``
-file. If it isn't, you can use the version you want. If you choose an incompatible
-version, Composer will throw dependency errors when you try to install. If
-this happens, you can try a different version.
+The README for a bundle (e.g. `FOSUserBundle`_) usually tells you its name
+(e.g. ``friendsofsymfony/user-bundle``). If it doesn't, you can search for
+the library on the `Packagist.org`_ site.
 
-Now you can add the bundle to your ``composer.json`` file and update the
-dependencies. You can do this manually:
-
-1. **Add it to the ``composer.json`` file:**
+.. note::
 
-   .. code-block:: json
+    Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
+    archive of Symfony Bundles.
 
-       {
-           ...,
-           "require": {
-               ...,
-               "friendsofsymfony/user-bundle": "2.0.*@dev"
-           }
-       }
+2) Install the Bundle via Composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-2. **Update the dependency:**
+Now that you know the package name, you can install it via Composer:
 
    .. code-block:: bash
 
-       $ php composer.phar update friendsofsymfony/user-bundle
-
-   or update all dependencies
-
-   .. code-block:: bash
+       $ php composer.phar require friendsofsymfony/user-bundle
 
-       $ php composer.phar update
+This will choose the best version for your project, add it to ``composer.json``
+and download the library into the ``vendor/`` directory. If you need a specific
+version, add a ``:`` and the version right after the library name (see
+`composer require`_).
 
-Or you can do this in one command:
-
-.. code-block:: bash
-
-    $ php composer.phar require friendsofsymfony/user-bundle:2.0.*@dev
-
-Enable the Bundle
------------------
+B) Enable the Bundle
+--------------------
 
 At this point, the bundle is installed in your Symfony project (in
 ``vendor/friendsofsymfony/``) and the autoloader recognizes its classes.
@@ -91,13 +68,13 @@ The only thing you need to do now is register the bundle in ``AppKernel``::
         }
     }
 
-Configure the Bundle
---------------------
+C) Configure the Bundle
+-----------------------
 
-Usually a bundle requires some configuration to be added to app's
-``app/config/config.yml`` file. The bundle's documentation will likely
-describe that configuration. But you can also get a reference of the
-bundle's config via the ``config:dump-reference`` command.
+It's pretty common for a bundle to need some additional setup or configuration
+in ``app/config/config.yml``. The bundle's documentation will tell you about
+the configuration, but you can also get a reference of the bundle's config
+via the ``config:dump-reference`` command.
 
 For instance, in order to look the reference of the ``assetic`` config you
 can use this:
@@ -132,10 +109,10 @@ Other Setup
 -----------
 
 At this point, check the ``README`` file of your brand new bundle to see
-what to do next.
+what to do next. Have fun!
 
 .. _their documentation: http://getcomposer.org/doc/00-intro.md
-.. _Packagist:           https://packagist.org
+.. _Packagist.org:       https://packagist.org
 .. _FOSUserBundle:       https://github.com/FriendsOfSymfony/FOSUserBundle
-.. _`friendsofsymfony/user-bundle`: https://packagist.org/packages/friendsofsymfony/user-bundle
-.. _KnpBundles:          http://knpbundles.com/
+.. _KnpBundles.com:      http://knpbundles.com/
+.. _`composer require`:  https://getcomposer.org/doc/03-cli.md#require

cookbook/form/unit_testing.rst

@@ -185,7 +185,7 @@ on other extensions. You need add those extensions to the factory object::
         {
             parent::setUp();
             
-            $validator = $this->getMock('\Symfony\Component\Validator\ValidatorInterface');
+            $validator = $this->getMock('\Symfony\Component\Validator\Validator\ValidatorInterface');
             $validator->method('validate')->will($this->returnValue(new ConstraintViolationList()));
 
             $this->factory = Forms::createFormFactoryBuilder()

cookbook/validation/custom_constraint.rst

@@ -65,22 +65,34 @@ The validator class is also simple, and only has one required method ``validate(
         public function validate($value, Constraint $constraint)
         {
             if (!preg_match('/^[a-zA-Za0-9]+$/', $value, $matches)) {
+                // If you're using the new 2.5 validation API (you probably are!)
+                $this->context->buildViolation($constraint->message)
+                    ->setParameter('%string%', $value)
+                    ->addViolation();
+                );
+
+                // If you're using the old 2.4 validation API
+                /*
                 $this->context->addViolation(
                     $constraint->message,
                     array('%string%' => $value)
                 );
+                */
             }
         }
     }
 
-.. note::
-
-    The ``validate`` method does not return a value; instead, it adds violations
-    to the validator's ``context`` property with an ``addViolation`` method
-    call if there are validation failures. Therefore, a value could be considered
-    as being valid if it causes no violations to be added to the context.
-    The first parameter of the ``addViolation`` call is the error message to
-    use for that violation.
+Inside ``validate``, you don't need to return a value. Instead, you add violations
+to the validator's ``context`` property and a value will be considered valid
+if it causes no violations. The ``buildViolation`` method takes the error
+message as its argument and returns an instance of
+:class:`Symfony\\Component\\Validator\\Violation\\ConstraintViolationBuilderInterface`.
+The ``addViolation`` method call finally adds the violation to the context.
+
+.. versionadded:: 2.5
+    The ``buildViolation`` method was added in Symfony 2.5. For usage examples
+    with older Symfony versions, see the corresponding versions of this documentation
+    page.
 
 Using the new Validator
 -----------------------

cookbook/workflow/_vendor_deps.rst.inc

@@ -24,29 +24,12 @@ To upgrade your libraries to new versions, run ``php composer.phar update``.
 
 .. tip::
 
-    If you want to add a new package to your application, modify the ``composer.json``
-    file:
-
-    .. code-block:: json
-
-        {
-            "require": {
-                ...
-                "doctrine/doctrine-fixtures-bundle": "@dev"
-            }
-        }
-
-    and then execute the ``update`` command for this specific package, i.e.:
-
-    .. code-block:: bash
-
-        $ php composer.phar update doctrine/doctrine-fixtures-bundle
-
-    You can also combine both steps into a single command:
+    If you want to add a new package to your application, run the composer
+    ``require`` command:
 
     .. code-block:: bash
 
-        $ php composer.phar require doctrine/doctrine-fixtures-bundle:@dev
+        $ php composer.phar require doctrine/doctrine-fixtures-bundle
 
 To learn more about Composer, see `GetComposer.org`_: