Firebase Admin SDK for PHP

Interact with Google Firebase from your PHP application.

License Stargazers Total downloads Community chat Sponsoring

Note

If you are interested in using the PHP Admin SDK as a client for end-user access (for example, in a web application), as opposed to admin access from a privileged environment (like a server), you should instead follow the instructions for setting up the client JavaScript SDK.

The source code can be found at https://github.com/kreait/firebase-php/ .

User Guide

Overview

Requirements

Installation

The recommended way to install the Firebase Admin SDK is with Composer. Composer is a dependency management tool for PHP that allows you to declare the dependencies your project needs and installs them into your project.

If you want to use the SDK within a Framework, please follow the installation instructions here:

composer require kreait/firebase-php:^4.43

Alternatively, you can specify the Firebase Admin SDK as a dependency in your project’s existing composer.json file:

 {
   "require": {
     "kreait/firebase-php": "^4.43"
   }
}

After installing, you need to require Composer’s autoloader:

<?php

require __DIR__.'/vendor/autoload.php';

You can find out more on how to install Composer, configure autoloading, and other best-practices for defining dependencies at getcomposer.org.

Please continue to the Setup section to learn more about connecting your application to Firebase.

Usage examples

You can find usage examples at https://github.com/jeromegamez/firebase-php-examples and in the tests directory of this project’s GitHub repository.

Issues/Support

License

Licensed using the MIT license.

Copyright (c) Jérôme Gamez <https://github.com/jeromegamez> <jerome@gamez.name>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributing

Guidelines
  1. The SDK utilizes PSR-1, PSR-2, PSR-4, and PSR-7.
  2. This SDK has a minimum PHP version requirement of PHP 7.0. Pull requests must not require a PHP version greater than PHP 7.0 unless the feature is only utilized conditionally.
  3. All pull requests must include unit tests to ensure the change works as expected and to prevent regressions.
Running the tests

The SDK is unit tested with PHPUnit. Run the tests using the Makefile:

make tests
Coding standards

The SDK uses the PHP Coding Standars Fixer to ensure a uniform coding style. Apply coding standard fixed using the Makefile:

make cs

from the root of the project.

Setup

Google Service Account

In order to access a Firebase project using a server SDK, you must authenticate your requests to Firebase with a Service Account.

Follow the steps described in the official Firebase documentation to create a Service Account for your Firebase application: Add the Firebase Admin SDK to your Server.

You can then configure the SDK to use this Service Account:

With the SDK

use Kreait\Firebase\Factory;

$factory = (new Factory)->withServiceAccount('/path/to/firebase_credentials.json');

With the Symfony Bundle

Please see https://github.com/kreait/firebase-bundle#configuration

With the Laravel/Lumen Package

Please see https://github.com/kreait/laravel-firebase#configuration

With autodiscovery

The SDK is able to autodiscover the Service Account for your project in the following conditions:

  1. Your application runs on Google Cloud Engine.
  2. The path to the JSON key file is defined in one of the following environment variables
    • FIREBASE_CREDENTIALS
    • GOOGLE_APPLICATION_CREDENTIALS
  3. The JSON Key file is located in Google’s “well known path”
    • on Linux/MacOS: $HOME/.config/gcloud/application_default_credentials.json
    • on Windows: $APPDATA/gcloud/application_default_credentials.json

If you want to use autodiscovery, a Service Account must not be explicitly configured.

Custom Database URI

Note

It is not necessary to define a custom database URI in most cases.

If the project ID in the JSON file does not match the URL of your Firebase application, or if you want to be explicit, you can configure the Factory like this:

use Kreait\Firebase\Factory;

$factory = (new Factory())
    ->withDatabaseUri('https://my-project.firebaseio.com');

Caching

Before connecting to the Firebase APIs, the SDK fetches an authentication token for your credentials. This authentication token is cached in-memory so that it can be re-used during the same process.

If you want to cache authentication tokens more effectively, you can provide any implementation of psr/cache to the Firebase factory when creating your Firebase instance.

Note

Authentication tokens are cached in-memory by default. For Symfony and Laravel, the Framework’s cache will automatically be used.

For Symfony and Laravel, the Framework’s cache will automatically be used.

Here is an example using the Symfony Cache Component:

use Symfony\Component\Cache\Simple\FilesystemCache;

$factory = $factory->withAuthTokenCache(new FilesystemCache());

In order to verify ID tokens, the verifier makes a call to fetch Firebase’s currently available public keys. The keys are cached in memory by default.

If you want to cache the public keys more effectively, you can provide any implementation of psr/simple-cache to the Firebase factory when creating your Firebase instance.

Note

Public keys tokens are cached in-memory by default. For Symfony and Laravel, the Framework’s cache will automatically be used.

Here is an example using the Symfony Cache Component:

use Symfony\Component\Cache\Simple\FilesystemCache;

$factory = $factory->withVerifierCache(new FilesystemCache());

End User Credentials

Note

While theoretically possible, it’s not recommended to use end user credentials in the context of a Server-to-Server backend application.

When using End User Credentials (for example if you set you application default credentials locally with gcloud auth application-default login), you need to provide the ID of the project you want to access directly and suppress warnings triggered by the Google Auth Component:

use Kreait\Firebase\Factory;

putenv('SUPPRESS_GCLOUD_CREDS_WARNING=true');

// This will use the project defined in the Service Account
// credentials files by default
$base = (new Factory())->withProjectId('firebase-project-id');

Cloud Messaging

Available since v4.5

You can use the Firebase Admin SDK for PHP to send Firebase Cloud Messaging messages to end-user devices. Specifically, you can send messages to individual devices, named topics, or condition statements that match one or more topics.

Note

Sending messages to Device Groups is only possible with legacy protocols which are not supported by this SDK.

Before you start, please read about Firebase Remote Config in the official documentation:

Initializing the Messaging component

With the SDK

$messaging = $factory->createMessaging();

With Dependency Injection (Symfony Bundle/Laravel/Lumen Package)

use Kreait\Firebase\Messaging;

class MyService
{
    public function __construct(Messaging $messaging)
    {
        $this->messaging = $messaging;
    }
}

With the Laravel app() helper (Laravel/Lumen Package)

$messaging = app('firebase.messaging');

Getting started

use Kreait\Firebase\Messaging\CloudMessage;

$message = CloudMessage::withTarget(/* see sections below */)
    ->withNotification(Notification::create('Title', 'Body'))
    ->withData(['key' => 'value']);

$messaging->send($message);

A message must be an object implementing Kreait\Firebase\Messaging\Message or an array that can be parsed to a Kreait\Firebase\Messaging\CloudMessage.

You can use Kreait\Firebase\Messaging\RawMessageFromArray to create a message without the SDK checking it for validity before sending it. This gives you full control over the sent message, but also means that you have to send/validate a message in order to know if it’s valid or not.

Note

If you notice that a field is not supported by the SDK yet, please open an issue on the issue tracker, so that others can benefit from it as well.

Send messages to topics

Based on the publish/subscribe model, FCM topic messaging allows you to send a message to multiple devices that have opted in to a particular topic. You compose topic messages as needed, and FCM handles routing and delivering the message reliably to the right devices.

For example, users of a local weather forecasting app could opt in to a “severe weather alerts” topic and receive notifications of storms threatening specified areas. Users of a sports app could subscribe to automatic updates in live game scores for their favorite teams.

Some things to keep in mind about topics:

  • Topic messaging supports unlimited topics and subscriptions for each app.
  • Topic messaging is best suited for content such as news, weather, or other publicly available information.
  • Topic messages are optimized for throughput rather than latency. For fast, secure delivery to single devices or small groups of devices, target messages to registration tokens, not topics.

You can create a message to a topic in one of the following ways:

use Kreait\Firebase\Messaging\CloudMessage;

$topic = 'a-topic';

$message = CloudMessage::withTarget('topic', $topic)
    ->withNotification($notification) // optional
    ->withData($data) // optional
;

$message = CloudMessage::fromArray([
    'topic' => $topic,
    'notification' => [/* Notification data as array */], // optional
    'data' => [/* data array */], // optional
]);

$messaging->send($message);

Send conditional messages

Warning

OR-conditions are currently not processed correctly by the Firebase Rest API, leading to undelivered messages. This can be resolved by splitting up a message to an OR-condition into multiple messages to AND-conditions. So one conditional message to 'a' in topics || 'b' in topics should be sent as two messages to the conditions 'a' in topics && !('b' in topics) and 'b' in topics && !('a' in topics)

References:

Sometimes you want to send a message to a combination of topics. This is done by specifying a condition, which is a boolean expression that specifies the target topics. For example, the following condition will send messages to devices that are subscribed to TopicA and either TopicB or TopicC:

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

FCM first evaluates any conditions in parentheses, and then evaluates the expression from left to right. In the above expression, a user subscribed to any single topic does not receive the message. Likewise, a user who does not subscribe to TopicA does not receive the message. These combinations do receive it:

  • TopicA and TopicB
  • TopicA and TopicC
use Kreait\Firebase\Messaging\CloudMessage;

$condition = "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)";

$message = CloudMessage::withTarget('condition', $condition)
    ->withNotification($notification) // optional
    ->withData($data) // optional
;

$message = CloudMessage::fromArray([
    'condition' => $condition,
    'notification' => [/* Notification data as array */], // optional
    'data' => [/* data array */], // optional
]);

$messaging->send($message);

Send messages to specific devices

The Admin FCM API allows you to send messages to individual devices by specifying a registration token for the target device. Registration tokens are strings generated by the client FCM SDKs for each end-user client app instance.

Each of the Firebase client SDKs are able to generate these registration tokens: iOS, Android, Web, C++, and Unity.

use Kreait\Firebase\Messaging\CloudMessage;

$deviceToken = '...';

$message = CloudMessage::withTarget('token', $deviceToken)
    ->withNotification($notification) // optional
    ->withData($data) // optional
;

$message = CloudMessage::fromArray([
    'token' => $deviceToken,
    'notification' => [/* Notification data as array */], // optional
    'data' => [/* data array */], // optional
]);

$messaging->send($message);

Send messages to multiple devices (Multicast)

Available since v4.24

You can send send one message to up to 500 devices:

use Kreait\Firebase\Messaging\CloudMessage;

$deviceTokens = ['...', '...' /* ... */];

$message = CloudMessage::new(); // Any instance of Kreait\Messaging\Message

$sendReport = $messaging->sendMulticast($message, $deviceTokens);

The returned value is an instance of Kreait\Firebase\Messaging\MulticastSendReport and provides you with methods to determine the successes and failures of the multicasted message:

$report = $messaging->sendMulticast($message, $deviceTokens);

echo 'Successful sends: '.$report->successes()->count().PHP_EOL;
echo 'Failed sends: '.$report->failures()->count().PHP_EOL;

if ($report->hasFailures()) {
    foreach ($report->failures()->getItems() as $failure) {
        echo $failure->error()->getMessage().PHP_EOL;
    }
}

Send multiple messages at once

Available since v4.29

You can send send up to 500 prepared messages (each message has a token, topic or condition as a target) in one go:

use ;

$messages = [
    // Up to 500 items, either objects implementing Kreait\Firebase\Messaging\Message
    // or arrays that can be used to create valid to Kreait\Firebase\Messaging\Cloudmessage instances
];

$message = CloudMessage::new(); // Any instance of Kreait\Messaging\Message

/** @var Kreait\Firebase\Messaging\MulticastSendReport $sendReport **/
$sendReport = $messaging->sendAll($messages);

Adding a notification

A notification is an instance of Kreait\Firebase\Messaging\Notification and can be created in one of the following ways. The title and the body of a notification are both optional.

use Kreait\Firebase\Messaging\Notification;

$title = 'My Notification Title';
$body = 'My Notification Body';
$imageUrl = 'http://lorempixel.com/400/200/';

$notification = Notification::fromArray([
    'title' => $title,
    'body' => $body,
    'image' => $imageUrl,
]);

$notification = Notification::create($title, $body);

$changedNotification = $notification
    ->withTitle('Changed title')
    ->withBody('Changed body)
    ->withImageUrl('http://lorempixel.com/200/400/');

Once you have created a message with one of the methods described below, you can attach the notification to it:

$message = $message->withNotification($notification);

Adding data

The data attached to a message must be an array of key-value pairs where all keys and values are strings.

Once you have created a message with one of the methods described below, you can attach data to it:

$data = [
    'first_key' => 'First Value',
    'second_key' => 'Second Value',
];

$message = $message->withData($data);

Changing the message target

You can change the target of an already created message with the withChangedTarget() method.

use Kreait\Firebase\Messaging\CloudMessage;

$deviceToken = '...';
$anotherDeviceToken = '...';

$message = CloudMessage::withTarget('token', $deviceToken)
    ->withNotification(['title' => 'My title', 'body' => 'My Body'])
;

$messaging->send($message);

$sameMessageToDifferentTarget = $message->withChangedTarget('token', $anotherDeviceToken);

Adding target platform specific configuration

You can target platforms specific configuration to your messages.

Android

You can find the full Android configuration reference in the official documentation: REST Resource: projects.messages.AndroidConfig

use Kreait\Firebase\Messaging\AndroidConfig;

// Example from https://firebase.google.com/docs/cloud-messaging/admin/send-messages#android_specific_fields
$config = AndroidConfig::fromArray([
    'ttl' => '3600s',
    'priority' => 'normal',
    'notification' => [
        'title' => '$GOOG up 1.43% on the day',
        'body' => '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
        'icon' => 'stock_ticker_update',
        'color' => '#f45342',
    ],
]);

$message = $message->withAndroidConfig($config);
APNs

You can find the full APNs configuration reference in the official documentation: REST Resource: projects.messages.ApnsConfig

use Kreait\Firebase\Messaging\ApnsConfig;

// Example from https://firebase.google.com/docs/cloud-messaging/admin/send-messages#apns_specific_fields
$config = ApnsConfig::fromArray([
    'headers' => [
        'apns-priority' => '10',
    ],
    'payload' => [
        'aps' => [
            'alert' => [
                'title' => '$GOOG up 1.43% on the day',
                'body' => '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
            ],
            'badge' => 42,
        ],
    ],
]);

$message = $message->withApnsConfig($config);
WebPush

You can find the full WebPush configuration reference in the official documentation: REST Resource: projects.messages.Webpush

use Kreait\Firebase\Messaging\WebPushConfig;

// Example from https://firebase.google.com/docs/cloud-messaging/admin/send-messages#webpush_specific_fields
$config = WebPushConfig::fromArray([
    'notification' => [
        'title' => '$GOOG up 1.43% on the day',
        'body' => '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
        'icon' => 'https://my-server/icon.png',
    ],
    'fcm_options' => [
        'link' => 'https://my-server/some-page',
    ],
]);

$message = $message->withWebPushConfig($config);

Adding platform independent FCM options

Available since v4.27

You can find the full FCM Options configuration reference in the official documentation: REST Resource: projects.messages.fcm_options

use Kreait\Firebase\Messaging\FcmOptions;

$fcmOptions = FcmOptions::create()
    ->withAnalyticsLabel('my-analytics-label');
// or
$fcmOptions = [
    'analytics_label' => 'my-analytics-label';
];

$message = $message->withFcmOptions($fcmOptions);

Using Emojis

Firebase Messaging supports Emojis in Messages.

Note

You can find a full list of all currently available Emojis at https://www.unicode.org/emoji/charts/full-emoji-list.html

// You can copy and paste an emoji directly into you source code
$text = "This is an emoji 😀";

// This only works in PHP ^7.0, double quotes are required
$text = "This is an emoji \u{1F600}";

Sending a fully configured raw message

Available since v4.27

Note

The message will be parsed and validated by the SDK.

use Kreait\Firebase\Messaging\RawMessageFromArray;

$message = new RawMessageFromArray([
        'notification' => [
            // https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification
            'title' => 'Notification title',
            'body' => 'Notification body',
            'image' => 'http://lorempixel.com/400/200/',
        ],
        'data' => [
            'key_1' => 'Value 1',
            'key_2' => 'Value 2',
        ],
        'android' => [
            // https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#androidconfig
            'ttl' => '3600s',
            'priority' => 'normal',
            'notification' => [
                'title' => '$GOOG up 1.43% on the day',
                'body' => '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
                'icon' => 'stock_ticker_update',
                'color' => '#f45342',
            ],
        ],
        'apns' => [
            // https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#apnsconfig
            'headers' => [
                'apns-priority' => '10',
            ],
            'payload' => [
                'aps' => [
                    'alert' => [
                        'title' => '$GOOG up 1.43% on the day',
                        'body' => '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
                    ],
                    'badge' => 42,
                ],
            ],
        ],
        'webpush' => [
            // https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushconfig
            'notification' => [
                'title' => '$GOOG up 1.43% on the day',
                'body' => '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
                'icon' => 'https://my-server/icon.png',
            ],
        ],
        'fcm_options' => [
            // https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#fcmoptions
            'analytics_label' => 'some-analytics-label'
        ]
    ]);

$messaging->send($message);

Validating messages

Available since v4.12

You can validate a message by sending a validation-only request to the Firebase REST API. If the message is invalid, a KreaitFirebaseExceptionMessagingInvalidMessage exception is thrown, which you can catch to evaluate the raw error message(s) that the API returned.

use Kreait\Firebase\Exception\Messaging\InvalidMessage;

try {
    $messaging->validate($message);
} catch (InvalidMessage $e) {
    print_r($e->errors());
}

Topic management

Available since v4.8
Subscribe to a topic

You can subscribe one or multiple devices to a topic by passing registration tokens to the subscribeToTopic() method.

$topic = 'my-topic';
$registrationTokens = [
    // ...
};

$messaging->subscribeToTopic($topic, $registrationTokens);

Note

You can subscribe up to 1,000 devices in a single request. If you provide an array with over 1,000 registration tokens, the operation will fail with an error.

Unsubscribe from a topic

You can unsubscribe one or multiple devices from a topic by passing registration tokens to the unsubscribeFromTopic() method.

$topic = 'my-topic';
$registrationTokens = [
    // ...
};

$messaging->unsubscribeFromTopic($topic, $registrationTokens);

Note

You can unsubscribe up to 1,000 devices in a single request. If you provide an array with over 1,000 registration tokens, the operation will fail with an error.

App instance management

Available since v4.28

A registration token is related to an application that generated it. You can retrieve current information about an app instance by passing a registration token to the getAppInstance() method.

$registrationToken = '...';

$appInstance = $messaging->getAppInstance($registrationToken);
// Return the full information as provided by the Firebase API
$instanceInfo = $appInstance->rawData();

/* Example output for an Android application instance:
    [
      "applicationVersion" => "1060100"
      "connectDate" => "2019-07-21"
      "attestStatus" => "UNKNOWN"
      "application" => "com.vendor.application"
      "scope" => "*"
      "authorizedEntity" => "..."
      "rel" => array:1 [
        "topics" => array:3 [
          "test-topic" => array:1 [
            "addDate" => "2019-07-21"
          ]
          "test-topic-5d35b46a15094" => array:1 [
            "addDate" => "2019-07-22"
          ]
          "test-topic-5d35b46b66c31" => array:1 [
            "addDate" => "2019-07-22"
          ]
        ]
      ]
      "connectionType" => "WIFI"
      "appSigner" => "..."
      "platform" => "ANDROID"
    ]
*/

/* Example output for a web application instance
    [
      "application" => "webpush"
      "scope" => ""
      "authorizedEntity" => "..."
      "rel" => array:1 [
        "topics" => array:2 [
          "test-topic-5d35b445b830a" => array:1 [
            "addDate" => "2019-07-22"
          ]
          "test-topic-5d35b446c0839" => array:1 [
            "addDate" => "2019-07-22"
          ]
        ]
      ]
      "platform" => "BROWSER"
    ]
*/

Note

As the data returned by the Google Instance ID API can return differently formed results depending on the application or platform, it is currently difficult to add reliable convenience methods for specific fields in the raw data.

Working with topic subscriptions

You can retrieve all topic subscriptions for an app instance with the topicSubscriptions() method:

$appInstance = $messaging->getAppInstance('<registration token>');

/** @var \Kreait\Firebase\Messaging\TopicSubscriptions $subscriptions */
$subscriptions = $appInstance->topicSubscriptions();

foreach ($subscriptions as $subscription) {
    echo "{$subscription->registrationToken()} is subscribed to {$subscription->topic()}\n";
}

Cloud Firestore

Available since v4.33

This SDK provides a bridge to the google/cloud-firestore package. You can enable the component in the SDK by adding the package to your project dependencies:

composer require google/cloud-firestore

Alternatively, you can specify the package as a dependency in your project’s existing composer.json file:

 {
   "require": {
     "google/cloud-firestore": "^1.8",
     "kreait/firebase-php": "^4.33"
   }
}

Note

The google/cloud-firestore package requires the gRPC PHP extension to be installed. You can find installation instructions for gRPC at github.com/grpc/grpc. The following projects aim to provide support for Firestore without the need to install the gRPC PHP extension, but have to be set up separately:

Before you start, please read about Firestore in the official documentation:

Initializing the Firestore component

With the SDK

$firestore = $factory->createFirestore();

With Dependency Injection (Symfony Bundle/Laravel/Lumen Package)

use Kreait\Firebase\Firestore;

class MyService
{
    public function __construct(Firestore $firestore)
    {
        $this->firestore = $firestore;
    }
}

With the Laravel app() helper (Laravel/Lumen Package)

$firestore = app('firebase.firestore');

Getting started

$database = $firestore->database();

$database is an instance of Google\Cloud\Firestore\FirestoreClient. Please refer to the links above for guidance on how to proceed from here.

Cloud Storage

Cloud Storage for Firebase stores your data in Google Cloud Storage, an exabyte scale object storage solution with high availability and global redundancy.

This SDK provides a bridge to the google/cloud-storage package. You can enable the component in the SDK by adding the package to your project dependencies:

Before you start, please read about Firebase Cloud Storage in the official documentation:

Initializing the Storage component

With the SDK

$storage = $factory->createStorage();

With Dependency Injection (Symfony Bundle/Laravel/Lumen Package)

use Kreait\Firebase\Storage;

class MyService
{
    public function __construct(Storage $storage)
    {
        $this->storage = $storage;
    }
}

With the Laravel app() helper (Laravel/Lumen Package)

$storage = app('firebase.storage');

Getting started

$storageClient = $storage->getStorageClient();
$defaultBucket = $storage->getBucket();
$anotherBucket = $storage->getBucket('another-bucket');

Default Storage bucket

Note

It is not necessary to change the default storage bucket in most cases.

The SDK assumes that your project’s default storage bucket name has the format <project-id>.appspot.com and will configure the storage instance accordingly.

If you want to change the default bucket your instance works with, you can specify the name when using the factory:

use Kreait\Firebase\Factory;

$storage = (new Factory())
    ->withDefaultStorageBucket('another-default-bucket')
    ->createStorage();

Realtime Database

Note

The Realtime Database API currently does not support realtime event listeners.

Initializing the Realtime Database component

With the SDK

$database = $factory->createDatabase();

With Dependency Injection (Symfony Bundle/Laravel/Lumen Package)

use Kreait\Firebase\Database;

class MyService
{
    public function __construct(Database $database)
    {
        $this->database = $database;
    }
}

With the Laravel app() helper (Laravel/Lumen Package)

$database = app('firebase.database');

Retrieving data

Every node in your database can be accessed through a Reference:

$reference = $database->getReference('path/to/child/location');

Note

Creating a reference does not result in a request to your Database. Requests to your Firebase applications are executed with the getSnapshot() and getValue() methods only.

You can then retrieve a Database Snapshot for the Reference or its value directly:

$snapshot = $reference->getSnapshot();

$value = $snapshot->getValue();
// or
$value = $reference->getValue();
Database Snapshots

Database Snapshots are immutable copies of the data at a Firebase Database location at the time of a query. The can’t be modified and will never change.

$snapshot = $reference->getSnapshot();
$value = $snapshot->getValue();

$value = $reference->getValue(); // Shortcut for $reference->getSnapshot()->getValue();

Snapshots provide additional methods to work with and analyze the contained value:

  • exists() returns true if the Snapshot contains any (non-null) data.
  • getChild() returns another Snapshot for the location at the specified relative path.
  • getKey() returns the key (last part of the path) of the location of the Snapshot.
  • getReference() returns the Reference for the location that generated this Snapshot.
  • getValue() returns the data contained in this Snapshot.
  • hasChild() returns true if the specified child path has (non-null) data.
  • hasChildren() returns true if the Snapshot has any child properties, i.e. if the value is an array.
  • numChildren() returns the number of child properties of this Snapshot, if there are any.
Queries

You can use Queries to filter and order the results returned from the Realtime Database. Queries behave exactly like References. That means you can execute any method on a Query that you can execute on a Reference.

Note

You can combine every filter query with every order query, but not multiple queries of each type. Shallow queries are a special case: they can not be combined with any other query method.

Shallow queries

This is an advanced feature, designed to help you work with large datasets without needing to download everything. Set this to true to limit the depth of the data returned at a location. If the data at the location is a JSON primitive (string, number or boolean), its value will simply be returned.

If the data snapshot at the location is a JSON object, the values for each key will be truncated to true.

Detailed information can be found on the official Firebase documentation page for shallow queries

$db->getReference('currencies')
    // order the reference's children by their key in ascending order
    ->shallow()
    ->getSnapshot();

A convenience method is available to retrieve the key names of a reference’s children:

$db->getReference('currencies')->getChildKeys(); // returns an array of key names
Ordering data

The official Firebase documentation explains How data is ordered.

Data is always ordered in ascending order.

You can only order by one property at a time - if you try to order by multiple properties, e.g. by child and by value, an exception will be thrown.

By key
$db->getReference('currencies')
    // order the reference's children by their key in ascending order
    ->orderByKey()
    ->getSnapshot();
By value

Note

In order to order by value, you must define an index, otherwise the Firebase API will refuse the query.

{
    "currencies": {
        ".indexOn": ".value"
    }
}

$db->getReference('currencies')
    // order the reference's children by their value in ascending order
    ->orderByValue()
    ->getSnapshot();
By child

Note

In order to order by a child value, you must define an index, otherwise the Firebase API will refuse the query.

{
    "people": {
        ".indexOn": "height"
    }
}

$db->getReference('people')
    // order the reference's children by the values in the field 'height' in ascending order
    ->orderByChild('height')
    ->getSnapshot();
Filtering data

To be able to filter results, you must also define an order.

limitToFirst
$db->getReference('people')
    // order the reference's children by the values in the field 'height'
    ->orderByChild('height')
    // limits the result to the first 10 children (in this case: the 10 shortest persons)
    // values for 'height')
    ->limitToFirst(10)
    ->getSnapshot();
limitToLast
$db->getReference('people')
    // order the reference's children by the values in the field 'height'
    ->orderByChild('height')
    // limits the result to the last 10 children (in this case: the 10 tallest persons)
    ->limitToLast(10)
    ->getSnapshot();
startAt
$db->getReference('people')
    // order the reference's children by the values in the field 'height'
    ->orderByChild('height')
    // returns all persons taller than or exactly 1.68 (meters)
    ->startAt(1.68)
    ->getSnapshot();
endAt
$db->getReference('people')
    // order the reference's children by the values in the field 'height'
    ->orderByChild('height')
    // returns all persons shorter than or exactly 1.98 (meters)
    ->endAt(1.98)
    ->getSnapshot();
equalTo
$db->getReference('people')
    // order the reference's children by the values in the field 'height'
    ->orderByChild('height')
    // returns all persons being exactly 1.98 (meters) tall
    ->equalTo(1.98)
    ->getSnapshot();

Saving data

Set/replace values

For basic write operations, you can use set() to save data to a specified reference, replacing any existing data at that path. For example a configuration array for a website might be set as follows:

$db->getReference('config/website')
   ->set([
       'name' => 'My Application',
       'emails' => [
           'support' => 'support@domain.tld',
           'sales' => 'sales@domain.tld',
       ],
       'website' => 'https://app.domain.tld',
      ]);

$db->getReference('config/website/name')->set('New name');

Note

Using set() overwrites data at the specified location, including any child nodes.

Update specific fields

To simultaneously write to specific children of a node without overwriting other child nodes, use the update() method.

When calling update(), you can update lower-level child values by specifying a path for the key. If data is stored in multiple locations to scale better, you can update all instances of that data using data fan-out.

For example, in a blogging app you might want to add a post and simultaneously update it to the recent activity feed and the posting user’s activity feed using code like this:

$uid = 'some-user-id';
$postData = [
    'title' => 'My awesome post title',
    'body' => 'This text should be longer',
];

// Create a key for a new post
$newPostKey = $db->getReference('posts')->push()->getKey();

$updates = [
    'posts/'.$newPostKey => $postData,
    'user-posts/'.$uid.'/'.$newPostKey => $postData,
];

$db->getReference() // this is the root reference
   ->update($updates);
Writing lists

Use the push() method to append data to a list in multiuser applications. The push() method generates a unique key every time a new child is added to the specified Firebase reference. By using these auto-generated keys for each new element in the list, several clients can add children to the same location at the same time without write conflicts. The unique key generated by push() is based on a timestamp, so list items are automatically ordered chronologically.

You can use the reference to the new data returned by the push() method to get the value of the child’s auto-generated key or set data for the child. The getKey() method of a push() reference contains the auto-generated key.

$postData = [...];
$postRef = $db->getReference('posts')->push($postData);

$postKey = $postRef->getKey(); // The key looks like this: -KVquJHezVLf-lSye6Qg
Server values

Server values can be written at a location using a placeholder value which is an object with a single .sv key. The value for that key is the type of server value you wish to set.

Firebase currently supports only one server value: timestamp. You can either set it manually in your write operation, or use a constant from the Firebase\Database class.

The following to usages are equivalent:

$ref = $db->getReference('posts/my-post')
          ->set('created_at', ['.sv' => 'timestamp']);

$ref = $db->getReference('posts/my-post')
          ->set('created_at', Database::SERVER_TIMESTAMP);
Delete data

You can delete a reference, including all data it contains, with the remove() method:

$db->getReference('posts')->remove();

You can also delete by specifying null as the value for another write operation such as set() or update().

$db->getReference('posts')->set(null);

You can use this technique with update() to delete multiple children in a single API call.

Database transactions

Note

Support for database transactions has been added in release 4.21.0

You can use transaction to update data according to its existing state. For example, if you want to increase an upvote counter, and want to make sure the count accurately reflects multiple, simultaneous upvotes, use a transaction to write the new value to the counter. Instead of two writes that change the counter to the same number, one of the write requests fails and you can then retry the request with the new value.

Replace data inside a transaction
use Kreait\Firebase\Database\Transaction;

$counterRef = $db->getReference('counter');

$db->runTransaction(function (Transaction $transaction) use ($counterRef) {

    // You have to snapshot the reference in order to change its value
    $counterSnapshot = $transaction->snapshot($counterRef);

    // Get the existing value from the snapshot
    $counter = $counterSnapshot->getValue() ?: 0;
    $newCounter = ++$counter;

    // If the value hasn't changed in the Realtime Database while we are
    // incrementing it, the transaction will be a success.
    $transaction->set($counterRef, $newCounter);
});
Delete data inside a transaction

Likewise, you can wrap the removal of a reference in a transaction as well: you can remove the reference only if it hasn’t changed in the meantime.

use Kreait\Firebase\Database\Transaction;

$toBeDeleted = $db->getReference('to-be-deleted');

$db->runTransaction(function (Transaction $transaction) use ($toBeDeleted) {

    $transaction->snapshot($toBeDeleted);

    $transaction->remove($toBeDeleted);
});
Handling transaction failures

If you haven’t snapshotted a reference before trying to change it, the operation will fail with a \Kreait\Firebase\Exception\Database\ReferenceHasNotBeenSnapshotted error.

If the reference has changed in the Realtime Database after you started the transaction, the transaction will fail with a \Kreait\Firebase\Exception\Database\TransactionFailed error.

use Kreait\Firebase\Database\Transaction;
use Kreait\Firebase\Exception\Database\ReferenceHasNotBeenSnapshotted;
use Kreait\Firebase\Exception\Database\TransactionFailed;

$ref = $db->getReference('my-ref');

try {
    $db->runTransaction(function (Transaction $transaction) use ($ref) {

        // $transaction->snapshot($ref);

        $ref->set('value change without a transaction');

        $transaction->set($ref, 'this will fail');
    });

} catch (ReferenceHasNotBeenSnapshotted $e) {

    $referenceInQuestion = $e->getReference();

    echo $e->getReference()->getUri().': '.$e->getMessage();

} catch (TransactionFailed $e) {

    $referenceInQuestion = $e->getReference();
    $failedRequest = $e->getRequest();
    $failureResponse = $e->getResponse();

    echo $e->getReference()->getUri().': '.$e->getMessage();

}

Debugging API exceptions

When a request to Firebase fails, the SDK will throw a \Kreait\Firebase\Exception\ApiException that includes the sent request and the received response object:

try {
    $db->getReference('forbidden')->getValue();
} catch (ApiException $e) {
    /** @var \Psr\Http\Message\RequestInterface $request */
    $request = $e->getRequest();
    /** @var \Psr\Http\Message\ResponseInterface|null $response */
    $response = $e->getResponse();

    echo $request->getUri().PHP_EOL;
    echo $request->getBody().PHP_EOL;

    if ($response) {
        echo $response->getBody();
    }
}

Database rules

Learn more about the usage of Firebase Realtime Database Rules in the official documentation.

use Kreait\Firebase\Database\RuleSet;

// The default rules allow full read and write access to authenticated users of your app
$ruleSet = RuleSet::default();

// This level of access means anyone can read or write to your database. You should
// configure more secure rules before launching your app.
$ruleSet = RuleSet::public();

// Private rules disable read and write access to your database by users.
// With these rules, you can only access the database through the
// Firebase console and the Admin SDKs.
$ruleSet = RuleSet::private();

// You can define custom rules
$ruleSet = RuleSet::fromArray(['rules' => [
    '.read' => true,
    '.write' => false,
    'users' => [
        '$uid' => [
            '.read' => '$uid === auth.uid',
            '.write' => '$uid === auth.uid',
        ]
    ]
]]);

$db->updateRules($ruleSet);

$freshRuleSet = $db->getRuleSet(); // Returns a new RuleSet instance
$actualRules = $ruleSet->getRules(); // returns an array

Authentication

Before you start, please read about Firebase Authentication in the official documentation:

Before you can access the Firebase Realtime Database from a server using the Firebase Admin SDK, you must authenticate your server with Firebase. When you authenticate a server, rather than sign in with a user account’s credentials as you would in a client app, you authenticate with a service account which identifies your server to Firebase.

You can get two different levels of access when you authenticate using the Firebase Admin SDK:

Administrative privileges: Complete read and write access to a project’s Realtime Database. Use with caution to complete administrative tasks such as data migration or restructuring that require unrestricted access to your project’s resources.

Limited privileges: Access to a project’s Realtime Database, limited to only the resources your server needs. Use this level to complete administrative tasks that have well-defined access requirements. For example, when running a summarization job that reads data across the entire database, you can protect against accidental writes by setting a read-only security rule and then initializing the Admin SDK with privileges limited by that rule.

Initializing the Auth component

With the SDK

$auth = $factory->createAuth();

With Dependency Injection (Symfony Bundle/Laravel/Lumen Package)

use Kreait\Firebase\Auth;

class MyService
{
    public function __construct(Auth $auth)
    {
        $this->auth = $auth;
    }
}

With the Laravel app() helper (Laravel/Lumen Package)

$auth = app('firebase.auth');

Create custom tokens

The Firebase Admin SDK has a built-in method for creating custom tokens. At a minimum, you need to provide a uid, which can be any string but should uniquely identify the user or device you are authenticating. These tokens expire after one hour.

$uid = 'some-uid';

$customToken = $auth->createCustomToken($uid);

You can also optionally specify additional claims to be included in the custom token. For example, below, a premiumAccount field has been added to the custom token, which will be available in the auth / request.auth objects in your Security Rules:

$uid = 'some-uid';
$additionalClaims = [
    'premiumAccount' => true
];

$customToken = $auth->createCustomToken($uid, $additionalClaims);

$customTokenString = (string) $customToken;

Note

This library uses lcobucci/jwt to work with JSON Web Tokens (JWT). You can find the usage instructions at https://github.com/lcobucci/jwt/blob/3.2/README.md.

Verify a Firebase ID Token

If a Firebase client app communicates with your server, you might need to identify the currently signed-in user. To do so, verify the integrity and authenticity of the ID token and retrieve the uid from it. You can use the uid transmitted in this way to securely identify the currently signed-in user on your server.

Note

Many use cases for verifying ID tokens on the server can be accomplished by using Security Rules for the Firebase Realtime Database and Cloud Storage. See if those solve your problem before verifying ID tokens yourself.

Warning

The ID token verification methods included in the Firebase Admin SDKs are meant to verify ID tokens that come from the client SDKs, not the custom tokens that you create with the Admin SDKs. See Auth tokens for more information.

Use Auth::verifyIdToken() to verify an ID token:

use Firebase\Auth\Token\Exception\InvalidToken;

$idTokenString = '...';

try {
    $verifiedIdToken = $auth->verifyIdToken($idTokenString);
} catch (\InvalidArgumentException $e) {
    echo 'The token could not be parsed: '.$e->getMessage();
} catch (InvalidToken $e) {
    echo 'The token is invalid: '.$e->getMessage();
}

$uid = $verifiedIdToken->getClaim('sub');
$user = $auth->getUser($uid);

Auth::verifyIdToken() accepts the following parameters:

Parameter Type Description
idToken string|Token (required) The ID token to verify
checkIfRevoked boolean (optional, default: false ) check if the ID token is revoked

Note

A leeway of 5 minutes is applied when verifying time based claims starting with release 4.25.0

Note

This library uses lcobucci/jwt to work with JSON Web Tokens (JWT). You can find the usage instructions at https://github.com/lcobucci/jwt/blob/3.2/README.md.

Custom Authentication Flows

Available since v4.41

Warning

It is recommended that you use the Firebase Client SDKs to perform user authentication. Once signed in via a client SDK, you should pass the logged-in user’s current ID token to your PHP endpoint and verify the ID token with each request to your backend.

Each of the methods documented below will return an instance of Kreait\Firebase\Auth\SignInResult\SignInResult with the following accessors:

use Kreait\Firebase\Auth;

// $signInResult = $auth->signIn*()

$signInResult->idToken(); // string|null
$signInResult->accessToken(); // string|null
$signInResult->refreshToken(); // string|null
$signInResult->data(); // array
$signInResult->asTokenResponse(); // array

SignInResult::data() returns the full payload of the response returned by the Firebase API, SignInResult::asTokenResponse() returns the Sign-In result in a format that can be returned to clients:

$tokenResponse = [
    'token_type' => 'Bearer',
    'access_token' => '...',
    'id_token' => '...',
    'refresh_token' => '...',
    'expires_in' => 3600,
];

Note

Not all sign-in methods return all types of tokens.

Anonymous Sign In

Note

This method will create a new user in the Firebase Auth User Database each time it is invoked

$signInResult = $auth->signInAnonymously();
Sign In with Email and Password
$signInResult = $auth->signInWithEmailAndPassword($email, $clearTextPassword);
Sign In with Email and Oob Code
$signInResult = $auth->signInWithEmailAndOobCode($email, $oobCode);
Sign In with a Custom Token
$signInResult = $auth->signInWithCustomToken($customToken);
Sign In with a Refresh Token
$signInResult = $auth->signInWithRefreshToken($refreshToken);
Sign In without a token
$signInResult = $auth->signInAsUser($userOrUid, array $claims = null);

Invalidate user sessions

This will revoke all sessions for a specified user and disable any new ID tokens for existing sessions from getting minted. Existing ID tokens may remain active until their natural expiration (one hour). To verify that ID tokens are revoked, use Auth::verifyIdToken() with the second parameter set to true.

If the check fails, a RevokedIdToken exception will be thrown.

use Kreait\Firebase\Exception\Auth\RevokedIdToken;

$auth->revokeRefreshTokens($uid);

try {
    $verifiedIdToken = $auth->verifyIdToken($idTokenString, $checkIfRevoked = true);
} catch (RevokedIdToken $e) {
    echo $e->getMessage();
}

Note

Because Firebase ID tokens are stateless JWTs, you can determine a token has been revoked only by requesting the token’s status from the Firebase Authentication backend. For this reason, performing this check on your server is an expensive operation, requiring an extra network round trip. You can avoid making this network request by setting up Firebase Rules that check for revocation rather than using the Admin SDK to make the check.

For more information, please visit Google: Detect ID token revocation in Database Rules

User management

The Firebase Admin SDK for PHP provides an API for managing your Firebase users with elevated privileges. The admin user management API gives you the ability to programmatically retrieve, create, update, and delete users without requiring a user’s existing credentials and without worrying about client-side rate limiting.

User Records

UserRecord s returned by methods from the Kreait\Firebase\Auth class have the following signature:

{
    "uid": "jEazVdPDhqec0tnEOG7vM5wbDyU2",
    "email": "user@domain.tld",
    "emailVerified": true,
    "displayName": null,
    "photoUrl": null,
    "phoneNumber": null,
    "disabled": false,
    "metadata": {
        "createdAt": "2018-02-14T15:41:32+00:00",
        "lastLoginAt": "2018-02-14T15:41:32+00:00"
    },
    "providerData": [
        {
            "uid": "user@domain.tld",
            "displayName": null,
            "email": "user@domain.tld",
            "photoUrl": null,
            "providerId": "password",
            "phoneNumber": null
        }
    ],
    "passwordHash": "UkVEQUNURUQ=",
    "customClaims": null,
    "tokensValidAfterTime": "2018-02-14T15:41:32+00:00"
}

List users

To enhance performance and prevent memory issues when retrieving a huge amount of users, this methods returns a Generator.

$users = $auth->listUsers($defaultMaxResults = 1000, $defaultBatchSize = 1000);

foreach ($users as $user) {
    /** @var \Kreait\Firebase\Auth\UserRecord $user */
    // ...
}
// or
array_map(function (\Kreait\Firebase\Auth\UserRecord $user) {
    // ...
}, iterator_to_array($users));

Get information about a specific user

$user = $auth->getUser('some-uid');
$user = $auth->getUserByEmail('user@domain.tld');
$user = $auth->getUserByPhoneNumber('+49-123-456789');

Create a user

The Admin SDK provides a method that allows you to create a new Firebase Authentication user. This method accepts an object containing the profile information to include in the newly created user account:

$userProperties = [
    'email' => 'user@example.com',
    'emailVerified' => false,
    'phoneNumber' => '+15555550100',
    'password' => 'secretPassword',
    'displayName' => 'John Doe',
    'photoUrl' => 'http://www.example.com/12345678/photo.png',
    'disabled' => false,
];

$createdUser = $auth->createUser($userProperties);

// This is equivalent to:

$request = \Kreait\Auth\Request\CreateUser::new()
    ->withUnverifiedEmail('user@example.com')
    ->withPhoneNumber('+15555550100')
    ->withClearTextPassword('secretPassword')
    ->withDisplayName('John Doe')
    ->withPhotoUrl('http://www.example.com/12345678/photo.png');

$createdUser = $auth->createUser($request);

By default, Firebase Authentication will generate a random uid for the new user. If you instead want to specify your own uid for the new user, you can include in the properties passed to the user creation method:

$properties = [
    'uid' => 'some-uid',
    // other properties
];

$request = \Kreait\Auth\Request\CreateUser::new()
    ->withUid('some-uid')
    // with other properties
;

Any combination of the following properties can be provided:

Property Type Description
uid string The uid to assign to the newly created user. Must be a string between 1 and 128 characters long, inclusive. If not provided, a random uid will be automatically generated.
email string The user’s primary email. Must be a valid email address.
emailVerified boolean Whether or not the user’s primary email is verified. If not provided, the default is false.
phoneNumber string The user’s primary phone number. Must be a valid E.164 spec compliant phone number.
password string The user’s raw, unhashed password. Must be at least six characters long.
displayName string The users’ display name.
photoURL string The user’s photo URL.
disabled boolean Whether or not the user is disabled. true for disabled; false for enabled. If not provided, the default is false.

Note

All of the above properties are optional. If a certain property is not specified, the value for that property will be empty unless a default is mentioned in the above table.

Note

If you provide none of the properties, an anonymous user will be created.

Update a user

Updating a user works exactly as creating a new user, except that the uid property is required:

$uid = 'some-uid';
$properties = [
    'displayName' => 'New display name'
];

$updatedUser = $auth->updateUser($uid, $properties);

$request = \Kreait\Auth\Request\UpdateUser::new()
    ->withDisplayName('New display name');

$updatedUser = $auth->updateUser($uid, $request);

In addition to the properties of a create request, the following properties can be provided:

Property Type Description
deletePhotoUrl boolean Whether or not to delete the user’s photo.
deleteDisplayName boolean Whether or not to delete the user’s display name.
deletePhoneNumber boolean Whether or not to delete the user’s phone number.
deleteProvider string|array One or more identity providers to delete.
customAttributes array A list of custom attributes which will be available in a User’s ID token.

Change a user’s password

$uid = 'some-uid';

$updatedUser = $auth->changeUserPassword($uid, 'new password');

Change a user’s email

$uid = 'some-uid';

$updatedUser = $auth->changeUserEmail($uid, 'user@domain.tld');

Disable a user

$uid = 'some-uid';

$updatedUser = $auth->disableUser($uid);

Enable a user

$uid = 'some-uid';

$updatedUser = $auth->enableUser($uid);

Update custom attributes

$uid = 'some-uid';
$customAttributes = [
    'admin' => true,
    'groupId' => '1234'
];

$updatedUser = $auth->setCustomUserAttributes($uid, $customAttributes);
$userWithDeletedCustomAttributes = $auth->deleteCustomUserAttributes($uid);

Note

Learn more about custom attributes/claims in the official documentation: Control Access with Custom Claims and Security Rules

Delete a user

$uid = 'some-uid';

$auth->deleteUser($uid);

Using Email Action Codes

Available since v4.37

The Firebase Admin SDK provides the ability to send users emails containing links they can use for password resets, email address verification, and email-based sign-in. These emails are sent by Google and have limited customizability.

If you want to instead use your own email templates and your own email delivery service, you can use the Firebase Admin SDK to programmatically generate the action links for the above flows, which you can include in emails to your users.

Action Code Settings

Note

Action Code Settings are optional.

Action Code Settings allow you to pass additional state via a continue URL which is accessible after the user clicks the email link. This also provides the user the ability to go back to the app after the action is completed. In addition, you can specify whether to handle the email action link directly from a mobile application when it is installed or from a browser.

For links that are meant to be opened via a mobile app, you’ll need to enable Firebase Dynamic Links and perform some tasks to detect these links from your mobile app. Refer to the instructions on how to configure Firebase Dynamic Links for email actions.

Parameter Type Description
continueUrl string|null Sets the continue URL
url string|null Alias for continueUrl
handleCodeInApp bool|null
Whether the email action link will be opened in a mobile app or a web link first.
The default is false. When set to true, the action code link will be be sent
as a Universal Link or Android App Link and will be opened by the app if
installed. In the false case, the code will be sent to the web widget first
and then on continue will redirect to the app if installed.
androidPackageName string|null
Sets the Android package name. This will try to open the link in an android app
if it is installed.
androidInstallApp bool|null
Whether to install the Android app if the device supports it and the app is not
already installed. If this field is provided without a androidPackageName,
an error is thrown explaining that the packageName must be provided in
conjunction with this field.
androidMinimumVersion string|null
If specified, and an older version of the app is installed,
the user is taken to the Play Store to upgrade the app.
The Android app needs to be registered in the Console.
iOSBundleId string|null
Sets the iOS bundle ID. This will try to open the link in an iOS app if it is
installed. The iOS app needs to be registered in the Console.

Example:

$actionCodeSettings = [
    'continueUrl' => 'https://www.example.com/checkout?cartId=1234',
    'handleCodeInApp' => true,
    'dynamicLinkDomain' => 'coolapp.page.link',
    'androidPackageName' => 'com.example.android',
    'androidMinimumVersion' => '12',
    'androidInstallApp' => true,
    'iOSBundleId' => 'com.example.ios',
];
Email verification

To generate an email verification link, provide the existing user’s unverified email and optional Action Code Settings. The email used must belong to an existing user. Depending on the method you use, an email will be sent to the user, or you will get an email action link that you can use in a custom email.

$link = $auth->getEmailVerificationLink($email);
$link = $auth->getEmailVerificationLink($email, $actionCodeSettings);

$auth->sendEmailVerificationLink($email);
$auth->sendEmailVerificationLink($email, $actionCodeSettings);
$auth->sendEmailVerificationLink($email, null, $locale);
$auth->sendEmailVerificationLink($email, $actionCodeSettings, $locale);
Password reset

To generate a password reset link, provide the existing user’s email and optional Action Code Settings. The email used must belong to an existing user. Depending on the method you use, an email will be sent to the user, or you will get an email action link that you can use in a custom email.

$link = $auth->getPasswordResetLink($email);
$link = $auth->getPasswordResetLink($email, $actionCodeSettings);

$auth->sendPasswordResetLink($email);
$auth->sendPasswordResetLink($email, $actionCodeSettings);
$auth->sendPasswordResetLink($email, null, $locale);
$auth->sendPasswordResetLink($email, $actionCodeSettings, $locale);
Confirm a password reset

Note

Out of the box, Firebase handles the confirmation of password reset requests. You can use your own server to handle account management emails by following the instructions on Customize account management emails and SMS messages

$oobCode = '...'; // Extract the OOB code from the request url (not scope of the SDK (yet :)))
$newPassword = '...';
$invalidatePreviousSessions = true; // default, will revoke current user refresh tokens

try {
    $auth->confirmPasswordReset($oobCode, $newPassword, $invalidatePreviousSessions);
} catch (\Kreait\Firebase\Exception\Auth\ExpiredOobCode $e) {
    // Handle the case of an expired reset code
} catch (\Kreait\Firebase\Exception\Auth\InvalidOobCode $e) {
    // Handle the case of an invalid reset code
} catch (\Kreait\Firebase\Exception\AuthException $e) {
    // Another error has occurred
}

Remote Config

Available since v4.3

Change the behavior and appearance of your app without publishing an app update.

Firebase Remote Config is a cloud service that lets you change the behavior and appearance of your app without requiring users to download an app update. When using Remote Config, you create in-app default values that control the behavior and appearance of your app.

Before you start, please read about Firebase Remote Config in the official documentation:

Before you begin

For Firebase projects created before the March 7, 2018 release of the Remote Config REST API, you must enable the API in the Google APIs console.

  1. Open the Firebase Remote Config API page in the Google APIs console.
  2. When prompted, select your Firebase project. (Every Firebase project has a corresponding project in the Google APIs console.)
  3. Click Enable on the Firebase Remote Config API page.

Initializing the Realtime Database component

With the SDK

$remoteConfig = $factory->createRemoteConfig();

With Dependency Injection (Symfony Bundle/Laravel/Lumen Package)

use Kreait\Firebase\RemoteConfig;

class MyService
{
    public function __construct(Database $remoteConfig)
    {
        $this->remoteConfig = $remoteConfig;
    }
}

With the Laravel app() helper (Laravel/Lumen Package)

$remoteConfig = app('firebase.remote_config');

Get the Remote Config

$template = $remoteConfig->get(); // Returns a Kreait\Firebase\RemoteConfig\Template

// Added in 4.29.0
$version = $template->version(); // Returns a Kreait\Firebase\RemoteConfig\Version

Create a new Remote Config

use Kreait\Firebase\RemoteConfig;

$template = RemoteConfig\Template::new();

Add a condition

use Kreait\Firebase\RemoteConfig;

$germanLanguageCondition = RemoteConfig\Condition::named('lang_german')
    ->withExpression("device.language in ['de', 'de_AT', 'de_CH']")
    ->withTagColor(TagColor::ORANGE); // The TagColor is optional

$template = $template->withCondition($germanLanguageCondition);

Add a parameter

use Kreait\Firebase\RemoteConfig;

$welcomeMessageParameter = Parameter::named('welcome_message')
        ->withDefaultValue('Welcome!')
        ->withDescription('This is a welcome message') // optional
;

Conditional values

use Kreait\Firebase\RemoteConfig;

$germanLanguageCondition = RemoteConfig\Condition::named('lang_german')
    ->withExpression("device.language in ['de', 'de_AT', 'de_CH']");

$germanWelcomeMessage = RemoteConfig\ConditionalValue::basedOn($germanLanguageCondition, 'Willkommen!');

$welcomeMessageParameter = Parameter::named('welcome_message')
        ->withDefaultValue('Welcome!')
        ->withConditionalValue($germanWelcomeMessage);

$template = $template
    ->withCondition($germanLanguageCondition)
    ->withParameter($welcomeMessageParameter);

Note

When you use a conditional value, make sure to add the corresponding condition to the template first.

Validation

Available since v4.16

Usually, the SDK will protect you from creating an invalid Remote Config template in the first place. If you want to be sure, you can validate the template with a call to the Firebase API:

use Kreait\Firebase\Exception\RemoteConfig\ValidationFailed;

try {
    $remoteConfig->validate($template);
} catch (ValidationFailed $e) {
    echo $e->getMessage();
}

Note

The ValidationFailed exception extends Kreait\Firebase\Exception\RemoteConfigException, so you can safely use the more generic exception type as well.

Publish the Remote Config

use Kreait\Firebase\Exception\RemoteConfigException

try {
    $remoteConfig->publish($template);
} catch (RemoteConfigException $e) {
    echo $e->getMessage();
}

Remote Config history

Available since v4.16

Since August 23, 2018, Firebase provides a change history for your published Remote configs.

The following properties are available from a Kreait\Firebase\RemoteConfig\Version object:

$version->versionNumber();
$version->user(); // The user/service account the performed the change
$version->description();
$version->updatedAt();
$version->updateOrigin();
$version->updateType();
$version->rollBackSource();
List versions

To enhance performance and prevent memory issues when retrieving a huge amount of versions, this methods returns a Generator.

foreach ($auth->listVersions() as $version) {
    /** @var \Kreait\Firebase\RemoteConfig\Version $version */
    // ...
}

// or

array_map(function (\Kreait\Firebase\RemoteConfig\Version $version) {
    // ...
}, iterator_to_array($auth->listVersions()));
Filtering
Available since v4.29

You can filter the results of RemoteConfig::listVersions():

use Kreait\Firebase\RemoteConfig\FindVersions;

$query = FindVersions::all()
    // Versions created/updated after August 1st, 2019 at midnight
    ->startingAt(new DateTime('2019-08-01 00:00:00'))
    // Versions created/updated before August 7th, 2019 at the end of the day
    ->endingAt(new DateTime('2019-08-06 23:59:59'))
    // Versions with version numbers smaller than 3464
    ->upToVersion(VersionNumber::fromValue(3463))
    // Setting a page size can results in faster first results,
    // but results in more request
    ->withPageSize(5)
    // Stop querying after the first 10 results
    ->withLimit(10)
;

// Alternative array notation

$query = [
    'startingAt' => '2019-08-01',
    'endingAt' => '2019-08-07',
    'upToVersion' => 9999,
    'pageSize' => 5,
    'limit' => 10,
];

foreach ($remoteConfig->listVersions($query) as $version) {
    echo "Version number: {$version->versionNumber()}\n";
    echo "Last updated at {$version->updatedAt()->format('Y-m-d H:i:s')}\n";
    // ...
    echo "\n---\n";
}
Get a specific version
$version = $remoteConfig->getVersion($versionNumber);
Rollback to a version
$template = $remoteConfig->rollbackToVersion($versionNumber);

Framework Integrations

kreait provides and maintains the following framework integrations for the Firebase Admin SDK for PHP:

CodeIgniter

tatter/firebase

Tutorials

You can find an example project implementing the Firebase Admin SDK for PHP at https://github.com/jeromegamez/firebase-php-examples .

In addition, the SDK has been featured in the following tutorials:

Videos

Note

Do you know another tutorial that is not featured in this list? Then please consider adding it by creating a Pull Request in the GitHub Repository of this project.

Troubleshooting

PHP Parse Error/PHP Syntax Error

If you’re getting an error in the likes of

PHP Parse error: syntax error, unexpected ':', expecting ';' or '{' in ...

the environment you are running the script in does not use PHP 7.x. You can check this by adding the line

echo phpversion(); exit;

somewhere in your script.

Class ‘Kreait\Firebase\ …’ not found

You are not using the latest release of the SDK, please update your composer dependencies.

Call to undefined function openssl_sign()

You need to install the OpenSSL PHP Extension: http://php.net/openssl

cURL error XX: …

If you receive a cURL error XX: ..., make sure that you have a current CA Root Certificates bundle on your system and that PHP uses it.

To see where PHP looks for the CA bundle, check the output of the following command:

var_dump(openssl_get_cert_locations());

which should lead to an output similar to this:

array(8) {
    'default_cert_file' =>
    string(32) "/usr/local/etc/openssl/cert.pem"
    'default_cert_file_env' =>
    string(13) "SSL_CERT_FILE"
    'default_cert_dir' =>
    string(29) "/usr/local/etc/openssl/certs"
    'default_cert_dir_env' =>
    string(12) "SSL_CERT_DIR"
    'default_private_dir' =>
    string(31) "/usr/local/etc/openssl/private"
    'default_default_cert_area' =>
    string(23) "/usr/local/etc/openssl"
    'ini_cafile' =>
    string(0) ""
    'ini_capath' =>
    string(0) ""
}

Now check if the file given in the default_cert_file field actually exists. Create a backup of the file, download the current CA bundle from https://curl.haxx.se/ca/cacert.pem and put it where default_cert_file points to.

If the problem still occurs, another possible solution is to configure the curl.cainfo setting in your php.ini:

[curl]
curl.cainfo = /absolute/path/to/cacert.pem

ID Tokens are issued in the future

When ID Token verification fails because of an IssuedInTheFuture exception, this is an indication that the system time in your environment is not set correctly.

If you chose to ignore the issue, you can catch the exception and return the ID token nonetheless:

use Firebase\Auth\Token\Exception\InvalidToken;
use Firebase\Auth\Token\Exception\IssuedInTheFuture;

$auth = $factory->createAuth();

try {
    return $auth->verifyIdToken($idTokenString);
} catch (IssuedInTheFuture $e) {
    return $e->getToken();
} catch (InvalidIdToken $e) {
    echo $e->getMessage();
    exit;
}

“403 Forbidden” Errors

Under the hood, a Firebase project is actually a Google Cloud project with pre-defined and pre-allocated permissions and resources.

When Google adds features to its product line, it is possible that you have to manually configure your Firebase/Google Cloud Project to take advantage of those new features.

When a request to the Firebase APIs fails, please make sure that the according Google Cloud API is enabled for your project:

Please also make sure that the Service Account you are using for your project has all necessary roles and permissions as described in the official documentation at Manage project access with Firebase IAM.

Proxy configuration

If you need to access the Firebase/Google APIs through a proxy, you can configure the SDK to use one via Guzzle’s proxy configuration:

$factory = $factory->withHttpProxy('tcp://<host>:<port>');

Debugging API requests

In order to debug HTTP requests to the Firebase/Google APIs, you can set Guzzle’s debug option to true in the HTTP client config:

$factory = $factory->withEnabledDebug();