Remove RegisteredClaimGiven exception in favour of deprecation message for withClaim

This PR is proposed as per the discussion in #559.

Author: Spomky

src/Builder.php

@@ -412,7 +412,11 @@ private function configureClaim($name, $value)
     public function withClaim($name, $value)
     {
         if (in_array($name, RegisteredClaims::ALL, true)) {
-            throw RegisteredClaimGiven::forClaim($name);
+            trigger_error('The use of the method "withClaim" is deprecated for registered claims. Please use dedicated method instead.', E_USER_DEPRECATED);
+        }
+
+        if ($name === RegisteredClaims::AUDIENCE) {
+            return $this->permittedFor($value);
         }
 
         return $this->configureClaim($name, $value);

test/unit/BuilderTest.php

@@ -564,15 +564,33 @@ public function withClaimMustKeepAFluentInterface()
     /**
      * @test
      *
+     * @param string $claim
+     * @param array $value
+     *
      * @covers ::__construct
      * @covers ::withClaim
      * @covers \Lcobucci\JWT\Token\RegisteredClaimGiven
+     *
+     * @dataProvider dataWithClaimDeprecationNotice
      */
-    public function withClaimShouldThrowExceptionWhenTryingToConfigureARegisteredClaim()
+    public function withClaimShouldSendDeprecationNoticeWhenTryingToConfigureARegisteredClaim($claim, $value)
     {
-        $this->expectException(RegisteredClaimGiven::class);
+        $this->expectDeprecation('The use of the method "withClaim" is deprecated for registered claims. Please use dedicated method instead.');
 
-        $this->createBuilder()->withClaim('sub', 'me');
+        $this->createBuilder()->withClaim($claim, $value);
+    }
+
+    public function dataWithClaimDeprecationNotice()
+    {
+        return [
+            ['sub', 'me'],
+            ['aud', 'him'],
+            ['jti', '0123456789ABCDEF'],
+            ['iss', 'you'],
+            ['exp', time()+3600],
+            ['iat', time()],
+            ['nbf', time()],
+        ];
     }
 
     /**