Firebase Bundle Laravel Package

Getting Started

First Steps

1. Installation

   composer require kreait/firebase-bundle:^6.1
   

   Add the bundle to config/bundles.php:

   Kreait\Firebase\Bundle\FirebaseBundle::class => ['all' => true],
   

2. Configuration Define Firebase credentials in .env:

   FIREBASE_CREDENTIALS=@file(/path/to/serviceAccountKey.json)
   

   Or use a URL:

   FIREBASE_CREDENTIALS=https://example.com/serviceAccountKey.json
   

3. First Use Case: AppCheck Integration

   use Kreait\Firebase\Auth\Auth;
   use Kreait\Firebase\Auth\AuthFactory;
   
   $authFactory = new AuthFactory();
   $auth = $authFactory->createAuth($credentials);
   
   // Enable AppCheck with cached keyset
   $auth->setAppCheckConfig([
       'keyset_cache' => [
           'handler' => new \Symfony\Component\Cache\Adapter\FilesystemAdapter(),
           'ttl' => 3600, // Cache keyset for 1 hour
       ],
   ]);
   

Implementation Patterns

Dependency Injection (DI) Integration

• Autowiring: The bundle auto-configures Auth, Database, Storage, and Messaging services.

  public function __construct(
      private Auth $auth,
      private Database $database,
      private Storage $storage
  ) {}
  

• AppCheck Configuration Configure AppCheck with keyset caching in Symfony services:

  # config/packages/kreait_firebase.yaml
  kreait_firebase:
      auth:
          settings:
              app_check:
                  keyset_cache:
                      handler: '@cache.app'
                      ttl: 3600
  

Common Workflows

1. AppCheck Integration

   • Verify AppCheck tokens with cached keyset:

     $auth->verifyAppCheckToken($appCheckToken);
     

   • Configure keyset cache in factory:

     $auth = $factory->createAuth($credentials, [
         'settings' => [
             'app_check' => [
                 'keyset_cache' => [
                     'handler' => new \Symfony\Component\Cache\Adapter\RedisAdapter(),
                     'ttl' => 3600,
                 ],
             ],
         ],
     ]);
     

2. User Authentication with AppCheck

   $auth->verifyIdToken($idToken, [
       'app_check_token' => $appCheckToken,
   ]);
   

Gotchas and Tips

Common Pitfalls

1. AppCheck Keyset Cache

   • Issue: Stale AppCheck keys if cache isn't properly configured.
   • Fix: Ensure cache handler is properly initialized and TTL is set:

     $factory->createAuth($credentials, [
         'settings' => [
             'app_check' => [
                 'keyset_cache' => [
                     'handler' => new \Symfony\Component\Cache\Adapter\ArrayAdapter(), // Fallback
                     'ttl' => 3600,
                 ],
             ],
         ],
     ]);
     

2. Cache Provider Compatibility

   • Issue: Not all cache adapters support the required methods.
   • Fix: Use Symfony's CacheItemPoolInterface compliant adapters (e.g., FilesystemAdapter, RedisAdapter).

3. AppCheck Token Validation

   • Issue: Forgetting to include app_check_token in verification requests.
   • Fix: Always pass the token when required:

     $auth->verifyIdToken($idToken, ['app_check_token' => $appCheckToken]);
     

Debugging Tips

• AppCheck Debugging Enable debug mode for AppCheck:

  $auth->setAppCheckConfig([
      'debug' => true,
      'keyset_cache' => [...],
  ]);
  

• Cache Validation Manually validate cache keyset:

  $cache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter();
  $keyset = $cache->get('firebase_appcheck_keyset', function() {
      return $auth->getAppCheckKeyset();
  });
  

Extension Points

1. Custom Keyset Cache Implement a custom cache handler for AppCheck keyset:

   $factory->createAuth($credentials, [
       'settings' => [
           'app_check' => [
               'keyset_cache' => [
                   'handler' => new class implements \Psr\Cache\CacheItemPoolInterface {
                       // Custom cache logic
                   },
                   'ttl' => 3600,
               ],
           ],
       ],
   ]);
   

2. AppCheck Middleware Add middleware to validate AppCheck tokens globally:

   $auth->setMiddleware(function(callable $next) {
       return function($request) use ($next) {
           if ($request->hasHeader('x-firebase-appcheck')) {
               $appCheckToken = $request->getHeader('x-firebase-appcheck')[0];
               $auth->verifyAppCheckToken($appCheckToken);
           }
           return $next($request);
       };
   });
   

3. Event-Driven AppCheck Listen to AppCheck-related events (e.g., keyset refresh):

   $dispatcher->addListener(
       FirebaseAppCheckKeysetRefreshedEvent::class,
       fn(FirebaseAppCheckKeysetRefreshedEvent $event) => $this->invalidateCache()
   );