Laravel Firebase Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require kreait/laravel-firebase
   

2. Publish the config (optional but recommended for customization):

   php artisan vendor:publish --provider="Kreait\Laravel\Firebase\ServiceProvider" --tag=config
   

3. Configure Firebase credentials:
   • Add your Firebase service account JSON file to storage/app/firebase-auth.json or set the FIREBASE_CREDENTIALS environment variable.
   • Set the FIREBASE_DATABASE_URL in your .env file:

     FIREBASE_DATABASE_URL=https://your-project-id.firebaseio.com
     

First Use Case: Authenticate a User

use Kreait\Laravel\Firebase\Facades\Firebase;

$user = Firebase::auth()->getUser('user-id');

Implementation Patterns

Dependency Injection

Inject the Firebase facade or components directly into your services:

use Kreait\Laravel\Firebase\Facades\Firebase;

class UserService {
    public function __construct(
        protected Firebase $firebase
    ) {}

    public function verifyToken(string $token): bool {
        return $this->firebase->auth()->verifyIdToken($token);
    }
}

Multiple Firebase Projects

Configure multiple projects in config/firebase.php:

'projects' => [
    'default' => [
        'database_url' => env('FIREBASE_DATABASE_URL'),
    ],
    'app' => [
        'database_url' => env('FIREBASE_APP_DATABASE_URL'),
    ],
],

Access a specific project:

$auth = Firebase::project('app')->auth();

Common Workflows

1. Firestore Operations:

   $doc = Firebase::firestore()->document('users/user-id')->get();
   

2. Realtime Database:

   $data = Firebase::database()->getReference('users/user-id')->getValue();
   

3. Messaging:

   Firebase::messaging()->sendMulticast([
       'tokens' => ['token1', 'token2'],
       'notification' => ['title' => 'Hello', 'body' => 'World'],
   ]);
   

Middleware Integration

Add HTTP middleware (e.g., for logging or retries):

'http_client_options' => [
    'middlewares' => [
        \Kreait\Firebase\Middleware\Retry::class,
        \Kreait\Firebase\Middleware\Logger::class,
    ],
],

Gotchas and Tips

Pitfalls

1. Credentials Auto-Discovery:

   • The package auto-discovers credentials via GOOGLE_APPLICATION_CREDENTIALS or FIREBASE_CREDENTIALS. If using a custom path, ensure it’s resolvable (e.g., storage/app/firebase-auth.json).
   • Avoid disabling auto-discovery unless explicitly setting credentials via config/environment variables.

2. PHP Version:

   • Requires PHP 8.3+ (Laravel 11+). Older versions will fail silently or throw errors.

3. Deprecated Facades:

   • Old facades (FirebaseAuth, FirebaseDatabase, etc.) are removed. Use Firebase::auth(), Firebase::database(), etc.

4. HTTP Timeouts:

   • Default timeout is 30 seconds (changed from ∞ in kreait/firebase-php 6.7.0). Override in http_client_options:

     'timeout' => 60, // in seconds
     

5. Firestore Default Database:

   • Override the default database name in config:

     'firestore' => [
         'default_database' => 'custom-db-name',
     ],
     

Debugging

1. Enable HTTP Debug Logging:

   'http_debug_log_channel' => 'single', // Logs to `storage/logs/firebase.log`
   

   Or via .env:

   FIREBASE_HTTP_DEBUG_LOG_CHANNEL=single
   

2. Token Caching:

   • Tokens are cached by default. Clear cache if issues arise:

     php artisan cache:clear
     

3. Multi-Project Conflicts:

   • Ensure database_url and project_id are unique per project in config/firebase.php.

Tips

1. Environment-Specific Configs: Use .env for secrets and config/firebase.php for project-specific settings:

   'projects' => [
       'staging' => [
           'database_url' => env('FIREBASE_STAGING_DATABASE_URL'),
       ],
   ],
   

2. Type Safety: Leverage PHP 8.3+ return types from the underlying SDK:

   $user = Firebase::auth()->getUser('user-id'); // Returns `Kreait\Firebase\Auth\User`
   

3. Testing:

   • Mock the facade in tests:

     $this->mock(Firebase::class)->shouldReceive('auth')->andReturnSelf();
     

   • Use firebase-php's test utilities for SDK-specific assertions.

4. Performance:

   • Reuse component instances (e.g., Firebase::auth()) instead of recreating them per request.

5. AppCheck:

   • Enable AppCheck for security:

     Firebase::appCheck()->verifyToken('app-check-token');