meraproject/vendor/kreait/firebase-tokens/MIGRATE-1.x-to-2.0.md

Migrating from from 1.x to 2.x

This guide will help you migrating from a 1.x to a 2.x version. If you are updating from a <1.9 version, consider updating to 1.9 first so that you can benefit from deprecation notices in your IDE.

Dependencies

JWT handling

lcobucci/jwt has been removed as the default JWT library. If you don't already have it in your project's dependencies, add it with composer require lcobucci/jwt:^3.2 or by adding it directly to the composer.json file in your project's root directory:

{
  "require": {
      "kreait/firebase-tokens": "^2.0",
      "lcobucci/jwt": "^3.2"
  }
}

The following JWT libraries are currently supported out of the box:

• lcobucci/jwt
• firebase/php-jwt

If you already have one of the supported JWT libraries present in your project, you can remove the previous lcobucci/jwt dependency.

HTTP handling

guzzlehttp/guzzle has been removed as the default HTTP handler. If you don't already have it in your project's dependencies, add it with composer require guzzlehttp/guzzle:^6.2.1 or by adding it directly to the composer.json file in your project's root directory:

{
  "require": {
      "kreait/firebase-tokens": "^2.0",
      "guzzlehttp/guzzle": "^6.2.1"
  }
}

Changed return values

Tokens

In 1.x, the Custom Token Generator and ID Token verifier returned instances of Lcobucci\JWT\Token.

In 2.0, the Custom Token Generator and ID Token verifier return instances of Kreait\Firebase\JWT\Contracts\Token.

Error Handling

In 1.x, specialized exceptions types were thrown for different kind of errors.

In 2.x, only one exception per action is thrown.

• Kreait\Firebase\JWT\Error\CustomTokenCreationFailed
• Kreait\Firebase\JWT\Error\IdTokenVerificationFailed

Changed usage

Custom Token Generator

Replace usages of Firebase\Auth\Token\Generator with Kreait\Firebase\JWT\CustomTokenGenerator:

1.x usage

<?php

// Before
use Firebase\Auth\Token\Generator;

$generator = new Generator($clientEmail, $privateKey);
$token = $generator->createCustomToken($uid, $claims);
// Returns an instance of Lcobucci\JWT\Token instance

2.0 usage

<?php

use Kreait\Firebase\JWT\CustomTokenGenerator;

$generator = CustomTokenGenerator::withClientEmailAndPrivateKey($clientEmail, $privateKey);
$token = $generator->createCustomToken($uid, $claims);
// Returns an instance of Kreait\Firebase\JWT\Contracts\Token

ID Token Verifier

Replace usages of Firebase\Auth\Token\Verifier with Kreait\Firebase\JWT\IdTokenVerifier:

1.x usage

<?php

use Firebase\Auth\Token\Verifier;

$verifier = new Verifier($projectId);

try {
    $verifiedIdToken = $verifier->verifyIdToken($idToken);
    
    echo $verifiedIdToken->getClaim('sub'); // "a-uid"
} catch (\Firebase\Auth\Token\Exception\ExpiredToken $e) {
    echo $e->getMessage();
} catch (\Firebase\Auth\Token\Exception\IssuedInTheFuture $e) {
    echo $e->getMessage();
} catch (\Firebase\Auth\Token\Exception\InvalidToken $e) {
    echo $e->getMessage();
}

2.0 usage

<?php

use Kreait\Firebase\JWT\Error\IdTokenVerificationFailed;
use Kreait\Firebase\JWT\IdTokenVerifier;

$verifier = IdTokenVerifier::createWithProjectId($projectId);

try {
    $verifier->verifyIdToken('header.payload.signature');
} catch (IdTokenVerificationFailed $e) {
    echo $e->getMessage();
    // Example Output:
    // The value 'idTokenString' is not a verified ID token:
    // - The token is invalid.
    // - Wrong number of segments
}