Remove mentions to non-existing container

This has confused enough people, let's just make things simpler and link to the configuration object for those who want to use. Signed-off-by: Luís Cobucci <[email protected]>
lcobucci · Aug 18, 2022 · fb752da · fb752da
1 parent 5f8262d
commit fb752da
Show file tree

Hide file tree

Showing 4 changed files with 135 additions and 100 deletions.
diff --git a/docs/issuing-tokens.md b/docs/issuing-tokens.md
@@ -1,59 +1,82 @@
 # Issuing tokens
 
-!!! Note
-    The examples here fetch the configuration object from a hypothetical dependency injection container.
-    You can create it in the same script or require it from a different file. It basically depends on how your system is bootstrapped.
-
-To issue new tokens you must create a new token a builder (easier when using the [configuration object](configuration.md)), customise it, and ask it to build the token:
+To issue new tokens you must create a new token a builder, customise it, and ask it to build the token:
 
 ```php
-use Lcobucci\JWT\Configuration;
+<?php
+declare(strict_types=1);
+
+use Lcobucci\JWT\Encoding\ChainedFormatter;
+use Lcobucci\JWT\Encoding\JoseEncoder;
+use Lcobucci\JWT\Signer\Key\InMemory;
+use Lcobucci\JWT\Signer\Hmac\Sha256;
+use Lcobucci\JWT\Token\Builder;
 
-$config = $container->get(Configuration::class);
-assert($config instanceof Configuration);
+require 'vendor/autoload.php';
+
+$tokenBuilder = (new Builder(new JoseEncoder(), ChainedFormatter::default()));
+$algorithm    = new Sha256();
+$signingKey   = InMemory::plainText(random_bytes(32));
 
 $now   = new DateTimeImmutable();
-$token = $config->builder()
-                // Configures the issuer (iss claim)
-                ->issuedBy('http://example.com')
-                // Configures the audience (aud claim)
-                ->permittedFor('http://example.org')
-                // Configures the id (jti claim)
-                ->identifiedBy('4f1g23a12aa')
-                // Configures the time that the token was issue (iat claim)
-                ->issuedAt($now)
-                // Configures the time that the token can be used (nbf claim)
-                ->canOnlyBeUsedAfter($now->modify('+1 minute'))
-                // Configures the expiration time of the token (exp claim)
-                ->expiresAt($now->modify('+1 hour'))
-                // Configures a new claim, called "uid"
-                ->withClaim('uid', 1)
-                // Configures a new header, called "foo"
-                ->withHeader('foo', 'bar')
-                // Builds a new token
-                ->getToken($config->signer(), $config->signingKey());
+$token = $tokenBuilder
+    // Configures the issuer (iss claim)
+    ->issuedBy('http://example.com')
+    // Configures the audience (aud claim)
+    ->permittedFor('http://example.org')
+    // Configures the id (jti claim)
+    ->identifiedBy('4f1g23a12aa')
+    // Configures the time that the token was issue (iat claim)
+    ->issuedAt($now)
+    // Configures the time that the token can be used (nbf claim)
+    ->canOnlyBeUsedAfter($now->modify('+1 minute'))
+    // Configures the expiration time of the token (exp claim)
+    ->expiresAt($now->modify('+1 hour'))
+    // Configures a new claim, called "uid"
+    ->withClaim('uid', 1)
+    // Configures a new header, called "foo"
+    ->withHeader('foo', 'bar')
+    // Builds a new token
+    ->getToken($algorithm, $signingKey);
+
+echo $token->toString();
 ```
 
 Once you've created a token, you're able to retrieve its data and convert it to its string representation:
 
 ```php
-use Lcobucci\JWT\Configuration;
+<?php
+declare(strict_types=1);
 
-$config = $container->get(Configuration::class);
-assert($config instanceof Configuration);
+use Lcobucci\JWT\Encoding\ChainedFormatter;
+use Lcobucci\JWT\Encoding\JoseEncoder;
+use Lcobucci\JWT\Signer\Key\InMemory;
+use Lcobucci\JWT\Signer\Hmac\Sha256;
+use Lcobucci\JWT\Token\Builder;
 
-$token = $config->builder()
-                ->issuedBy('http://example.com')
-                ->withClaim('uid', 1)
-                ->withHeader('foo', 'bar')
-                ->getToken($config->signer(), $config->signingKey());
+require 'vendor/autoload.php';
+
+$tokenBuilder = (new Builder(new JoseEncoder(), ChainedFormatter::default()));
+$algorithm    = new Sha256();
+$signingKey   = InMemory::plainText(random_bytes(32));
+
+$token = $tokenBuilder
+    ->issuedBy('http://example.com')
+    ->withClaim('uid', 1)
+    ->withHeader('foo', 'bar')
+    ->getToken($algorithm, $signingKey);
 
 $token->headers(); // Retrieves the token headers
 $token->claims(); // Retrieves the token claims
 
-echo $token->headers()->get('foo'); // will print "bar"
-echo $token->claims()->get('iss'); // will print "http://example.com"
-echo $token->claims()->get('uid'); // will print "1"
+echo $token->headers()->get('foo'), PHP_EOL; // will print "bar"
+echo $token->claims()->get('iss'), PHP_EOL; // will print "http://example.com"
+echo $token->claims()->get('uid'), PHP_EOL; // will print "1"
+
+echo $token->toString(), PHP_EOL; // The string representation of the object is a JWT string
 
-echo $token->toString(); // The string representation of the object is a JWT string
 ```
+
+!!! Note
+    Some systems make use of components to handle dependency injection.
+    If your application follows that practice, using a [configuration object](configuration.md) might simplify the wiring of this library.
diff --git a/docs/parsing-tokens.md b/docs/parsing-tokens.md
@@ -1,29 +1,37 @@
 # Parsing tokens
 
-!!! Note
-    The examples here fetch the configuration object from a hypothetical dependency injection container.
-    You can create it in the same script or require it from a different file. It basically depends on how your system is bootstrapped.
-
-To parse a token you must create a new parser (easier when using the [configuration object](configuration.md)) and ask it to parse a string:
+To parse a token you must create a new parser and ask it to parse a string:
 
 ```php
-use Lcobucci\JWT\Configuration;
+<?php
+declare(strict_types=1);
+
+use Lcobucci\JWT\Encoding\CannotDecodeContent;
+use Lcobucci\JWT\Encoding\JoseEncoder;
+use Lcobucci\JWT\Token\InvalidTokenStructure;
+use Lcobucci\JWT\Token\Parser;
+use Lcobucci\JWT\Token\UnsupportedHeaderFound;
 use Lcobucci\JWT\UnencryptedToken;
 
-$config = $container->get(Configuration::class);
-assert($config instanceof Configuration);
+require 'vendor/autoload.php';
 
-$token = $config->parser()->parse(
-    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'
-    . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.'
-    . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q'
-);
+$parser = new Parser(new JoseEncoder());
 
+try {
+    $token = $parser->parse(
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'
+        . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.'
+        . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q'
+    );
+} catch (CannotDecodeContent | InvalidTokenStructure | UnsupportedHeaderFound $e) {
+    echo 'Oh no, an error: ' . $e->getMessage();
+}
 assert($token instanceof UnencryptedToken);
 
-$token->headers(); // Retrieves the token headers
-$token->claims(); // Retrieves the token claims
+echo $token->claims()->get('sub'), PHP_EOL; // will print "1234567890"
+
 ```
 
-!!! Important
-    In case of parsing errors the Parser will throw an exception of type `InvalidArgumentException`.
+!!! Note
+    Some systems make use of components to handle dependency injection.
+    If your application follows that practice, using a [configuration object](configuration.md) might simplify the wiring of this library.
diff --git a/docs/validating-tokens.md b/docs/validating-tokens.md
@@ -1,36 +1,36 @@
 # Validating tokens
 
-!!! Note
-    The examples here fetch the configuration object from a hypothetical dependency injection container.
-    You can create it in the same script or require it from a different file. It basically depends on how your system is bootstrapped.
-
-To validate a token you must create a new validator (easier when using the [configuration object](configuration.md)) and assert or validate a token.
+To validate a token you must create a new validator and assert or validate a token.
 
 ## Using `Lcobucci\JWT\Validator#assert()`
 
-!!! Warning
-    You **MUST** provide at least one constraint, otherwise `\Lcobucci\JWT\Validation\NoConstraintsGiven` exception will be thrown.
-
 This method goes through every single constraint in the set, groups all the violations, and throws an exception with the grouped violations:
 
 ```php
-use Lcobucci\JWT\Configuration;
-use Lcobucci\JWT\UnencryptedToken;
+<?php
+declare(strict_types=1);
+
+use Lcobucci\JWT\Encoding\JoseEncoder;
+use Lcobucci\JWT\Token\Parser;
+use Lcobucci\JWT\Validation\Constraint\RelatedTo;
 use Lcobucci\JWT\Validation\RequiredConstraintsViolated;
+use Lcobucci\JWT\Validation\Validator;
+
+require 'vendor/autoload.php';
 
-$config = $container->get(Configuration::class);
-assert($config instanceof Configuration);
+$parser = new Parser(new JoseEncoder());
 
-$token = $config->parser()->parse('...');
-assert($token instanceof UnencryptedToken);
+$token = $parser->parse(
+    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'
+    . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.'
+    . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q'
+);
 
-// validation constraints can be set in the configuration with
-// the setValidationConstraints() setter
-// see the Customisation part of the Configuration documentation
-$constraints = $config->validationConstraints();
+$validator = new Validator();
 
 try {
-    $config->validator()->assert($token, ...$constraints);
+    $validator->assert($token, new RelatedTo('1234567891')); // doesn't throw na exception
+    $validator->assert($token, new RelatedTo('1234567890'));
 } catch (RequiredConstraintsViolated $e) {
     // list of constraints violation exceptions:
     var_dump($e->violations());
@@ -39,31 +39,43 @@ try {
 
 ## Using `Lcobucci\JWT\Validator#validate()`
 
-!!! Warning
-    You **MUST** provide at least one constraint, otherwise `\Lcobucci\JWT\Validation\NoConstraintsGiven` exception will be thrown.
-
 The difference here is that we'll always get a `boolean` result and stop in the very first violation:
 
 ```php
-use Lcobucci\JWT\Configuration;
-use Lcobucci\JWT\UnencryptedToken;
+<?php
+declare(strict_types=1);
+
+use Lcobucci\JWT\Encoding\JoseEncoder;
+use Lcobucci\JWT\Token\Parser;
+use Lcobucci\JWT\Validation\Constraint\RelatedTo;
+use Lcobucci\JWT\Validation\Validator;
+
+require 'vendor/autoload.php';
+
+$parser = new Parser(new JoseEncoder());
 
-$config = $container->get(Configuration::class);
-assert($config instanceof Configuration);
+$token = $parser->parse(
+    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.'
+    . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.'
+    . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q'
+);
 
-$token = $config->parser()->parse('...');
-assert($token instanceof UnencryptedToken);
+$validator = new Validator();
 
-// validation constraints can be set in the configuration with
-// the setValidationConstraints() setter
-// see the Customisation part of the Configuration documentation
-$constraints = $config->validationConstraints();
+if (! $validator->validate($token, new RelatedTo('1234567891'))) {
+    echo 'Invalid token (1)!', PHP_EOL; // will print this
+}
 
-if (! $config->validator()->validate($token, ...$constraints)) {
-   throw new RuntimeException('No way!');
+if (! $validator->validate($token, new RelatedTo('1234567890'))) {
+    echo 'Invalid token (2)!', PHP_EOL; // will not print this
 }
 ```
 
+!!! Note
+    Some systems make use of components to handle dependency injection.
+    If your application follows that practice, using a [configuration object](configuration.md) might simplify the wiring of this library.
+
+
 ## Available constraints
 
 This library provides the following constraints:
@@ -75,14 +87,6 @@ This library provides the following constraints:
 * `Lcobucci\JWT\Validation\Constraint\SignedWith`: verifies if the token was signed with the expected signer and key
 * `Lcobucci\JWT\Validation\Constraint\StrictValidAt`: verifies presence and validity of the claims `iat`, `nbf`, and `exp` (supports leeway configuration)
 * `Lcobucci\JWT\Validation\Constraint\LooseValidAt`: verifies the claims `iat`, `nbf`, and `exp`, when present (supports leeway configuration)
-* `Lcobucci\JWT\Validation\Constraint\HasClaimWithValue`: verifies that a custom claim has the expected value (not recommended when comparing cryptographic hashes)
-
-Example code for adding a constraint to the configuration object:
-
-```php
-use Lcobucci\JWT\Validation\Constraint\PermittedFor;
-
-$config->setValidationConstraints(new PermittedFor('your-aud-claim'));
-```
+* `Lcobucci\JWT\Validation\Constraint\HasClaimWithValue`: verifies that a **custom claim** has the expected value (not recommended when comparing cryptographic hashes)
 
 You may also create your [own validation constraints](extending-the-library.md#validation-constraints).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,10 +8,10 @@ nav:
     - 'quick-start.md'
     - 'supported-algorithms.md'
   - Usage:
-    - 'configuration.md'
     - 'issuing-tokens.md'
     - 'parsing-tokens.md'
     - 'validating-tokens.md'
+    - 'configuration.md'
   - Guides:
     - 'extending-the-library.md'
     - 'upgrading.md'