Laravel Firebase Laravel Package

## Getting Started

### Minimal Setup
1. **Install the package**:
   ```bash
   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_DATABASE_URL (e.g., FIREBASE_DATABASE_URL=https://your-project.firebaseio.com) to .env.
   • Place your service account JSON file in storage/app/firebase-auth.json or set FIREBASE_CREDENTIALS in .env to its path.

4. First use case:

   use Kreait\Laravel\Firebase\Facades\Firebase;
   
   // Get the Auth component (default project)
   $auth = Firebase::auth();
   $user = $auth->getUser('user-id');
   

Implementation Patterns

Dependency Injection (Recommended)

use Kreait\Laravel\Firebase\Facades\Firebase;

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

    public function getUserData(string $uid) {
        $auth = $this->firebase->auth();
        return $auth->getUser($uid);
    }
}

Facade Usage

// Default project
$auth = Firebase::auth();
$database = Firebase::database();

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

Common Workflows

1. Authentication:

   $auth = Firebase::auth();
   $user = $auth->getUser('uid');
   $customToken = $auth->createCustomToken($uid);
   

2. Realtime Database:

   $database = Firebase::database();
   $ref = $database->getReference('path/to/data');
   $snapshot = $ref->getSnapshot();
   

3. Firestore:

   $firestore = Firebase::firestore();
   $document = $firestore->document('collection/doc');
   $data = $document->data();
   

4. Storage:

   $storage = Firebase::storage();
   $bucket = $storage->bucket();
   $file = $bucket->upload('local-path', ['name' => 'remote-name']);
   

Middleware Injection (Advanced)

// config/firebase.php
'http_client_options' => [
    'middlewares' => [
        \App\Http\Middleware\FirebaseLoggingMiddleware::class,
    ],
],

Multi-Project Management

// config/firebase.php
'projects' => [
    'default' => [
        'database_url' => env('FIREBASE_DATABASE_URL'),
    ],
    'app' => [
        'database_url' => env('FIREBASE_APP_DATABASE_URL'),
        'credentials' => [
            'type' => 'service_account',
            // ... rest of the credentials
        ],
    ],
],

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

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).
   • Fix: Explicitly set FIREBASE_CREDENTIALS in .env if auto-discovery fails.

2. PHP Version:

   • Requires PHP 8.3+ (since v7.0.0). Older versions will fail silently or throw errors.
   • Fix: Update your PHP version or pin to an older package version (e.g., kreait/laravel-firebase:6.x).

3. Deprecated Facades:

   • Old facades (FirebaseAuth, FirebaseDatabase, etc.) are removed in v4.0.0+.
   • Fix: Use Kreait\Laravel\Firebase\Facades\Firebase facade instead.

4. HTTP Timeouts:

   • Default HTTP timeout is 30 seconds (changed in kreait/firebase-php v6.7.0).
   • Fix: Configure in config/firebase.php:

     'http_client_options' => [
         'timeout' => 60, // in seconds
     ],
     

5. Firestore Default Database:

   • The default database name is (default). Override via config:

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

Debugging Tips

1. Enable HTTP Debug Logging:

   // config/firebase.php
   'logging' => [
       'http_debug_log_channel' => 'stack', // or 'single'
   ],
   

   • Logs will appear in Laravel’s log channels (e.g., storage/logs/laravel.log).

2. Token Caching:

   • The package caches authentication tokens by default. Clear cache if tokens expire unexpectedly:

     $auth = Firebase::auth();
     $auth->getFactory()->getAuth()->clearTokenCache();
     

3. Multi-Project Issues:

   • Ensure each project in config/firebase.php has unique database_url or project_id.
   • Fix: Validate with:

     Firebase::projects(); // Lists all configured projects
     

Performance Tips

1. Reuse Components:

   • Firebase components (e.g., Auth, Database) are singletons. Inject them once and reuse:

     $auth = Firebase::auth(); // Reused across requests
     

2. Batch Operations:

   • Use Firestore’s batch() or Database’s update() for bulk writes to reduce API calls:

     $batch = $firestore->batch();
     $batch->set($doc1, $data1);
     $batch->set($doc2, $data2);
     $batch->commit();
     

3. Environment-Specific Configs:

   • Use Laravel’s config() helper to dynamically switch configs:

     $config = config("firebase.{$env}");
     

Extension Points

1. Custom HTTP Client:

   • Replace the default Guzzle client by binding your own:

     $this->app->bind(
         \Kreait\Firebase\Firebase::class,
         fn () => Firebase::createApp(
             $this->app->make(\Kreait\Firebase\Auth::class),
             $this->app->make(\Kreait\Firebase\Http\Client::class)
         )
     );
     

2. Event Listeners:

   • Listen to Firebase events (e.g., auth state changes) via Laravel’s event system:

     // Example: Listen for user creation
     event(new UserCreated($user));
     

3. Testing:

   • Mock Firebase components in tests using Laravel’s Mockery:

     $mockAuth = Mockery::mock(\Kreait\Firebase\Auth::class);
     $this->app->instance(\Kreait\Firebase\Auth::class, $mockAuth);
     

4. AppCheck Integration:

   • Enable AppCheck for security:

     $appCheck = Firebase::appCheck();
     $token = $appCheck->createToken('app');
     

   • Configure in config/firebase.php:

     'app_check' => [
         'api_key' => env('FIREBASE_APP_CHECK_API_KEY'),
     ],
     

---