feature #15882 Easier Custom Authentication errors (weaverryan)

This PR was merged into the 2.8 branch.

Discussion
----------

Easier Custom Authentication errors

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | not yet

This makes failing authentication with a custom message much easier:

```php
throw CustomAuthenticationException::createWithSafeMessage(
    'That was a ridiculous username'
);

// or
$e = new CustomAuthenticationException();
$e->setSafeMessage('That was a ridiculous username');

throw $e;
```

Currently, to do this, you'd need to create a new sub-class of `AuthenticationException`, which is way more work than it needs to be. The original design was so that all messages exposed are safe, which is why I've named the methods like I have.

Thanks!

Commits
-------

d7c1463 Adding a class to make it easier to set custom authentication error messages

src/Symfony/Component/Security/Core/Exception/CustomUserMessageAuthenticationException.php

@@ -0,0 +1,79 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Exception;
+
+/**
+ * An authentication exception where you can control the message shown to the user.
+ *
+ * Be sure that the message passed to this exception is something that
+ * can be shown safely to your user. In other words, avoid catching
+ * other exceptions and passing their message directly to this class.
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>
+ */
+class CustomUserMessageAuthenticationException extends AuthenticationException
+{
+    private $messageKey;
+
+    private $messageData = array();
+
+    public function __construct($message = '', array $messageData = array(), $code = 0, \Exception $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+
+        $this->setSafeMessage($message, $messageData);
+    }
+
+    /**
+     * Set a message that will be shown to the user.
+     *
+     * @param string $messageKey  The message or message key
+     * @param array  $messageData Data to be passed into the translator
+     */
+    public function setSafeMessage($messageKey, array $messageData = array())
+    {
+        $this->messageKey = $messageKey;
+        $this->messageData = $messageData;
+    }
+
+    public function getMessageKey()
+    {
+        return $this->messageKey;
+    }
+
+    public function getMessageData()
+    {
+        return $this->messageData;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function serialize()
+    {
+        return serialize(array(
+            parent::serialize(),
+            $this->messageKey,
+            $this->messageData,
+        ));
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function unserialize($str)
+    {
+        list($parentData, $this->messageKey, $this->messageData) = unserialize($str);
+
+        parent::unserialize($parentData);
+    }
+}

src/Symfony/Component/Security/Core/Tests/Exception/CustomUserMessageAuthenticationExceptionTest.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Tests\Exception;
+
+use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
+
+class CustomUserMessageAuthenticationExceptionTest extends \PHPUnit_Framework_TestCase
+{
+    public function testConstructWithSAfeMessage()
+    {
+        $e = new CustomUserMessageAuthenticationException('SAFE MESSAGE', array('foo' => true));
+
+        $this->assertEquals('SAFE MESSAGE', $e->getMessageKey());
+        $this->assertEquals(array('foo' => true), $e->getMessageData());
+        $this->assertEquals('SAFE MESSAGE', $e->getMessage());
+    }
+}