Firebase Admin SDK for PHP

Apr 05, 2020

Contents

1 User Guide 3

1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.3 Usage examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.1.4 Issues/Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.1.5 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.1.6 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2.1 Google Service Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2.2 Custom Database URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.2.3 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.2.4 End User Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.3 Cloud Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.3.1 Initializing the Messaging component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.3.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.3 Send messages to topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.4 Send conditional messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.3.5 Send messages to speciﬁc devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3.6 Send messages to multiple devices (Multicast) . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3.7 Send multiple messages at once . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3.8 Adding a notiﬁcation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.3.9 Adding data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.3.10 Changing the message target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.3.11 Adding target platform speciﬁc conﬁguration . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.3.12 Adding platform independent FCM options . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.3.13 Using Emojis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.3.14 Sending a fully conﬁgured raw message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.3.15 Validating messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.3.16 Topic management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.3.17 App instance management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.4 Cloud Firestore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.4.1 Initializing the Firestore component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.4.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.5 Cloud Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.5.1 Initializing the Storage component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.5.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.5.3 Default Storage bucket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.6 Realtime Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.6.1 Initializing the Realtime Database component . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.6.2 Retrieving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.6.3 Saving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.6.4 Database transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.6.5 Debugging API exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.6.6 Database rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.7 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

1.7.1 Initializing the Auth component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

1.7.2 Create custom tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.7.3 Verify a Firebase ID Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.7.4 Custom Authentication Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

1.7.5 Invalidate user sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

1.8 User management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

1.8.1 User Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

1.8.2 List users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

1.8.3 Get information about a speciﬁc user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

1.8.4 Create a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

1.8.5 Update a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

1.8.6 Change a user’s password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.8.7 Change a user’s email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.8.8 Disable a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.8.9 Enable a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.8.10 Update custom attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.8.11 Delete a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

1.8.12 Using Email Action Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

1.9 Dynamic Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

1.9.1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

1.9.2 Initializing the Dynamic Links component . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

1.9.3 Create a Dynamic Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

1.9.4 Create a short link from a long link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

1.9.5 Get link statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

1.9.6 Advanced usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

1.10 Remote Conﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

1.10.1 Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

1.10.2 Initializing the Realtime Database component . . . . . . . . . . . . . . . . . . . . . . . . . 46

1.10.3 Get the Remote Conﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

1.10.4 Create a new Remote Conﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

1.10.5 Add a condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

1.10.6 Add a parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

1.10.7 Conditional values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

1.10.8 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

1.10.9 Publish the Remote Conﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.10.10 Remote Conﬁg history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.11 Framework Integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

1.11.1 Laravel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

1.11.2 Symfony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.11.3 CodeIgniter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.12 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.12.1 Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.12.2 Videos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.13 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.13.1 PHP Parse Error/PHP Syntax Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.13.2 Class ‘Kreait\Firebase\ . . . ’ not found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

1.13.3 Call to undeﬁned function openssl_sign() . . . . . . . . . . . . . . . . . . . . . . . . 51

1.13.4 cURL error XX: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

1.13.5 ID Tokens are issued in the future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

1.13.6 “403 Forbidden” Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

1.13.7 Proxy conﬁguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

1.13.8 Debugging API requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

iii

Firebase Admin SDK for PHP

Interact with Google Firebase from your PHP application.

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/ﬁrebase-php/ .

Contents 1

Firebase Admin SDK for PHP

2 Contents

CHAPTER 1

User Guide

1.1 Overview

1.1.1 Requirements

• PHP >= 7.0

• The mbstring PHP extension

• A Firebase project - create a new project in the Firebase console, if you don’t already have one.

• A Google service account, follow the instructions in the ofﬁcial Firebase Server documentation and place the

JSON conﬁguration ﬁle somewhere in your project’s path.

1.1.2 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:

• Laravel: kreait/laravel-ﬁrebase

• Symfony: kreait/ﬁrebase-bundle

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 ﬁle:

{

"require": {

"kreait/firebase-php": "^4.43"

}

Firebase Admin SDK for PHP

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

<?php

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

You can ﬁnd out more on how to install Composer, conﬁgure autoloading, and other best-practices for deﬁning depen-

dencies at getcomposer.org.

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

1.1.3 Usage examples

You can ﬁnd usage examples at https://github.com/jeromegamez/ﬁrebase-php-examples and in the tests directory of

this project’s GitHub repository.

1.1.4 Issues/Support

• For bugs, feature requests and past issues: Github issue tracker

• For help with and discussion about the PHP SDK: Discord channel dedicated to this library

• For questions about Firebase in general: Stack Overﬂow and the Firebase Slack Community.

1.1.5 License

Licensed using the MIT license.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associ-

ated documentation ﬁles (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, ARIS-

ING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER

DEALINGS IN THE SOFTWARE.

1.1.6 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.

4 Chapter 1. User Guide

Firebase Admin SDK for PHP

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 Makeﬁle:

make tests

Coding standards

The SDK uses the PHP Coding Standars Fixer to ensure a uniform coding style. Apply coding standard ﬁxed using

the Makeﬁle:

make cs

from the root of the project.

1.2 Setup

1.2.1 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 ofﬁcial Firebase documentation to create a Service Account for your Firebase appli-

cation: Add the Firebase Admin SDK to your Server.

You can then conﬁgure 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/ﬁrebase-bundle#conﬁguration

With the Laravel/Lumen Package

Please see https://github.com/kreait/laravel-ﬁrebase#conﬁguration

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 ﬁle is deﬁned in one of the following environment variables

• FIREBASE_CREDENTIALS

• GOOGLE_APPLICATION_CREDENTIALS

3. The JSON Key ﬁle is located in Google’s “well known path”

1.2. Setup 5

Firebase Admin SDK for PHP

• 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 conﬁgured.

1.2.2 Custom Database URI

Note: It is not necessary to deﬁne a custom database URI in most cases.

If the project ID in the JSON ﬁle does not match the URL of your Firebase application, or if you want to be explicit,

you can conﬁgure the Factory like this:

use Kreait\Firebase\Factory;

$factory = (new Factory())

->withDatabaseUri('https://my-project.firebaseio.com');

1.2.3 Caching

Before connecting to the Firebase APIs, the SDK fetches an authentication token for your credentials. This authenti-

cation 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 veriﬁer 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());

6 Chapter 1. User Guide

Firebase Admin SDK for PHP

1.2.4 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');

1.3 Cloud Messaging

You can use the Firebase Admin SDK for PHP to send Firebase Cloud Messaging messages to end-user devices.

Speciﬁcally, 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 Conﬁg in the ofﬁcial documentation:

• Introduction to Firebase Cloud Messaging

• Introduction to Admin FCM API

1.3.1 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;

}

1.3. Cloud Messaging 7

Firebase Admin SDK for PHP

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

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

1.3.2 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 ﬁeld is not supported by the SDK yet, please open an issue on the issue tracker, so that

others can beneﬁt from it as well.

1.3.3 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

notiﬁcations of storms threatening speciﬁed 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

;

(continues on next page)

8 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

$message = CloudMessage::fromArray([

'topic' => $topic,

'notification' => [/

Notification data as array

/], // optional

'data' => [/

data array

/], // optional

]);

$messaging->send($message);

1.3.4 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:

• https://github.com/ﬁrebase/quickstart-js/issues/183

• https://stackoverﬂow.com/a/52302136/284325

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 speciﬁes 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 ﬁrst 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);

1.3. Cloud Messaging 9

Firebase Admin SDK for PHP

1.3.5 Send messages to speciﬁc 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);

1.3.6 Send messages to multiple devices (Multicast)

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;

}

1.3.7 Send multiple messages at once

10 Chapter 1. User Guide

Firebase Admin SDK for PHP

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);

1.3.8 Adding a notiﬁcation

A notiﬁcation 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 notiﬁcation 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 notiﬁcation to it:

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

1.3.9 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);

1.3. Cloud Messaging 11

Firebase Admin SDK for PHP

1.3.10 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);

1.3.11 Adding target platform speciﬁc conﬁguration

You can target platforms speciﬁc conﬁguration to your messages.

Android

You can ﬁnd the full Android conﬁguration reference in the ofﬁcial documentation: REST Resource:

projects.messages.AndroidConﬁg

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 ﬁnd the full APNs conﬁguration reference in the ofﬁcial documentation: REST Resource:

projects.messages.ApnsConﬁg

use Kreait\Firebase\Messaging\ApnsConfig;

// Example from https://firebase.google.com/docs/cloud-messaging/admin/send-messages

˓→#apns_specific_fields

(continues on next page)

12 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

$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 ﬁnd the full WebPush conﬁguration reference in the ofﬁcial 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);

1.3.12 Adding platform independent FCM options

You can ﬁnd the full FCM Options conﬁguration reference in the ofﬁcial documentation: REST Resource:

projects.messages.fcm_options

use Kreait\Firebase\Messaging\FcmOptions;

$fcmOptions = FcmOptions::create()

->withAnalyticsLabel('my-analytics-label');

// or

$fcmOptions = [

(continues on next page)

1.3. Cloud Messaging 13

Firebase Admin SDK for PHP

(continued from previous page)

'analytics_label' => 'my-analytics-label';

];

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

1.3.13 Using Emojis

Firebase Messaging supports Emojis in Messages.

Note: You can ﬁnd 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}";

1.3.14 Sending a fully conﬁgured raw message

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',

(continues on next page)

14 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

'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);

1.3.15 Validating messages

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());

}

1.3. Cloud Messaging 15

Firebase Admin SDK for PHP

1.3.16 Topic management

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.

1.3.17 App instance management

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"

(continues on next page)

16 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

"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 difﬁcult to add reliable convenience methods for speciﬁc ﬁelds 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

(continues on next page)

1.3. Cloud Messaging 17

Firebase Admin SDK for PHP

(continued from previous page)

$subscriptions = $appInstance->topicSubscriptions();

foreach ($subscriptions as $subscription) {

echo "{$subscription->registrationToken()} is subscribed to {$subscription->

˓→topic()}\n";

}

1.4 Cloud Firestore

This SDK provides a bridge to the google/cloud-ﬁrestore 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 ﬁle:

{

"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 ﬁnd

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:

• ahsankhatri/ﬁrestore-php

• morrislaptop/ﬁrestore-php

Before you start, please read about Firestore in the ofﬁcial documentation:

• Ofﬁcial Documentation

• google/cloud-ﬁrestore on GitHub

• PHP API Documentation

• PHP Usage Examples

1.4.1 Initializing the Firestore component

With the SDK

$firestore = $factory->createFirestore();

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

18 Chapter 1. User Guide

Firebase Admin SDK for PHP

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');

1.4.2 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.

1.5 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 ofﬁcial documentation:

• Firebase Cloud Storage

• Introduction to the Admin Cloud Storage API

• PHP API Documentation

• PHP Usage examples

1.5.1 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)

{

(continues on next page)

1.5. Cloud Storage 19

Firebase Admin SDK for PHP

(continued from previous page)

$this->storage = $storage;

}

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

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

1.5.2 Getting started

$storageClient = $storage->getStorageClient();

$defaultBucket = $storage->getBucket();

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

1.5.3 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 conﬁgure 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();

1.6 Realtime Database

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

1.6.1 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

{

(continues on next page)

20 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

public function __construct(Database $database)

{

$this->database = $database;

}

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

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

1.6.2 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 modiﬁed 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 speciﬁed 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 speciﬁed 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.

1.6. Realtime Database 21

Firebase Admin SDK for PHP

Queries

You can use Queries to ﬁlter 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 ﬁlter 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 ofﬁcial 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 ofﬁcial 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 deﬁne an index, otherwise the Firebase API will refuse the query.

22 Chapter 1. User Guide

Firebase Admin SDK for PHP

{

"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 deﬁne 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 ﬁlter results, you must also deﬁne 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

1.6. Realtime Database 23

Firebase Admin SDK for PHP

$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();

1.6.3 Saving data

Set/replace values

For basic write operations, you can use set() to save data to a speciﬁed reference, replacing any existing data at that

path. For example a conﬁguration array for a website might be set as follows:

$db->getReference('config/website')

->set([

'name' => 'My Application',

'emails' => [

'support' => '[email protected]',

'sales' => '[email protected]',

(continues on next page)

24 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

'website' => 'https://app.domain.tld',

]);

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

Note: Using set() overwrites data at the speciﬁed location, including any child nodes.

Update speciﬁc ﬁelds

To simultaneously write to speciﬁc 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 speciﬁed 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 conﬂicts.

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

1.6. Realtime Database 25

Firebase Admin SDK for PHP

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.

1.6.4 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 reﬂects 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;

(continues on next page)

26 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

// 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();

(continues on next page)

1.6. Realtime Database 27

Firebase Admin SDK for PHP

(continued from previous page)

$failedRequest = $e->getRequest();

$failureResponse = $e->getResponse();

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

}

1.6.5 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();

}

1.6.6 Database rules

Learn more about the usage of Firebase Realtime Database Rules in the ofﬁcial 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' => [

(continues on next page)

28 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

'.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

1.7 Authentication

Before you start, please read about Firebase Authentication in the ofﬁcial documentation:

• Introduction to the Admin Database API

• Create custom tokens

• Verify ID Tokens

• Revoke refresh tokens

Before you can access the Firebase Realtime Database from a server using the Firebase Admin SDK, you must authen-

ticate 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 identiﬁes 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-deﬁned 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.

1.7.1 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;

}

1.7. Authentication 29

Firebase Admin SDK for PHP

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

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

1.7.2 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 premiu-

mAccount ﬁeld 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 ﬁnd the usage instructions at

https://github.com/lcobucci/jwt/blob/3.2/README.md.

1.7.3 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 veriﬁcation 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 = '...';

(continues on next page)

30 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

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 ﬁnd the usage instructions at

https://github.com/lcobucci/jwt/blob/3.2/README.md.

1.7.4 Custom Authentication Flows

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:

1.7. Authentication 31

Firebase Admin SDK for PHP

$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();

$signInResult = $auth->signInWithEmailAndPassword($email, $clearTextPassword);

$signInResult = $auth->signInWithEmailAndOobCode($email, $oobCode);

$signInResult = $auth->signInWithCustomToken($customToken);

$signInResult = $auth->signInWithRefreshToken($refreshToken);

$signInResult = $auth->signInAsUser($userOrUid, array $claims = null);

1.7.5 Invalidate user sessions

This will revoke all sessions for a speciﬁed 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.

32 Chapter 1. User Guide

Firebase Admin SDK for PHP

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

1.8 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.

1.8.1 User Records

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

{

"uid": "jEazVdPDhqec0tnEOG7vM5wbDyU2",

"email": "[email protected]",

"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": "[email protected]",

"displayName": null,

"email": "[email protected]",

"photoUrl": null,

"providerId": "password",

"phoneNumber": null

}

"passwordHash": "UkVEQUNURUQ=",

(continues on next page)

1.8. User management 33

Firebase Admin SDK for PHP

(continued from previous page)

"customClaims": null,

"tokensValidAfterTime": "2018-02-14T15:41:32+00:00"

}

1.8.2 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));

1.8.3 Get information about a speciﬁc user

$user = $auth->getUser('some-uid');

$user = $auth->getUserByEmail('[email protected]');

$user = $auth->getUserByPhoneNumber('+49-123-456789');

1.8.4 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 proﬁle information to include in the newly created user account:

$userProperties = [

'email' => '[email protected]',

'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('[email protected]')

->withPhoneNumber('+15555550100')

->withClearTextPassword('secretPassword')

->withDisplayName('John Doe')

->withPhotoUrl('http://www.example.com/12345678/photo.png');

(continues on next page)

34 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

$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.

emailVerifiedbooleanWhether or not the user’s primary email is veriﬁed. If not provided, the default is false.

phoneNumberstring 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.

displayNamestring The users’ display name.

photoURL string The user’s photo URL.

disabled booleanWhether 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 speciﬁed, 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.

1.8.5 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');

(continues on next page)

1.8. User management 35

Firebase Admin SDK for PHP

(continued from previous page)

$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.

1.8.6 Change a user’s password

$uid = 'some-uid';

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

1.8.7 Change a user’s email

$uid = 'some-uid';

$updatedUser = $auth->changeUserEmail($uid, '[email protected]');

1.8.8 Disable a user

$uid = 'some-uid';

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

1.8.9 Enable a user

$uid = 'some-uid';

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

1.8.10 Update custom attributes

$uid = 'some-uid';

$customAttributes = [

'admin' => true,

'groupId' => '1234'

];

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

$userWithDeletedCustomAttributes = $auth->deleteCustomUserAttributes($uid);

36 Chapter 1. User Guide

Firebase Admin SDK for PHP

Note: Learn more about custom attributes/claims in the ofﬁcial documentation: Control Access with Custom Claims

and Security Rules

1.8.11 Delete a user

$uid = 'some-uid';

$auth->deleteUser($uid);

1.8.12 Using Email Action Codes

The Firebase Admin SDK provides the ability to send users emails containing links they can use for password resets,

email address veriﬁcation, 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 ﬂows, 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 conﬁgure Firebase Dynamic

Links for email actions.

1.8. User management 37

Firebase Admin SDK for PHP

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 ﬁrst.

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

installed. In the false case, the code

will be sent to the web widget ﬁrst

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 ﬁeld is

provided without a

androidPackageName,

an error is thrown explaining that

the packageName must be provided

conjunction with this ﬁeld.

androidMinimumVersion string|null

If speciﬁed, 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.

38 Chapter 1. User Guide

Firebase Admin SDK for PHP

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 veriﬁcation

To generate an email veriﬁcation link, provide the existing user’s unveriﬁed 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);

Email link for sign-in

Note: Before you can authenticate users with email link sign-in, you will need to enable email link sign-in for your

Firebase project.

Note: Unlike password reset and email veriﬁcation, the email used does not necessarily need to belong to an existing

user, as this operation can be used to sign up new users into your app via email link.

1.8. User management 39

Firebase Admin SDK for PHP

Note: The ActionCodeSettings object is required in this case to provide information on where to return the user after

the link is clicked for sign-in completion.

To generate a sign-in link, provide the user’s email and Action Code Settings. 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->getSignInWithEmailLink($email, $actionCodeSettings);

$auth->sendSignInWithEmailLink($email, $actionCodeSettings);

$auth->sendSignInWithEmailLink($email, $actionCodeSettings, $locale);

Conﬁrm a password reset

Note: Out of the box, Firebase handles the conﬁrmation 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

}

1.9 Dynamic Links

You can create short Dynamic Links with the Firebase Admin SDK for PHP. Dynamic Links can be

• a long Dynamic Link

• an array containing Dynamic Link parameters

• an action created with builder methods

and will return a URL like https://example.page.link/wXYZ.

Note: Short Dynamic Links created via the REST API or this SDK do not show up in the Firebase console. Such

Dynamic Links are intended for user-to-user sharing. For marketing use cases, continue to create your links directly

through the Dynamic Links page of the Firebase console.

40 Chapter 1. User Guide

Firebase Admin SDK for PHP

Before you start, please read about Dynamic Links in the ofﬁcial documentation:

• Dynamic Links Product Page

• Create Dynamic Links with the REST API

• Long Dynamic Links

• Dynamic Link API Reference

1.9.1 Getting started

• In the Firebase console, open the Dynamic Links section.

• If you have not already accepted the terms of service and set a domain for your Dynamic Links, do so when

prompted.

• If you already have a Dynamic Links domain, take note of it. You need to provide a Dynamic Links Domain

when you programmatically create Dynamic Links.

1.9.2 Initializing the Dynamic Links component

With the SDK

$dynamicLinksDomain = 'https://example.page.link';

$dynamicLinks = $factory->createDynamicLinksService($dynamicLinksDomain);

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

To deﬁne the default Dynamic Links Domain for Laravel, conﬁgure the

FIREBASE_DYNAMIC_LINKS_DEFAULT_DOMAIN environment variable.

use Kreait\Firebase\DynamicLinks;

class MyService

{

public function __construct(DynamicLinks $dynamicLinks)

{

$this->dynamicLinks = $dynamicLinks;

}

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

To deﬁne the default Dynamic Links Domain, conﬁgure the FIREBASE_DYNAMIC_LINKS_DEFAULT_DOMAIN

environment variable.

$dynamicLinks = app('firebase.dynamic_links');

1.9.3 Create a Dynamic Link

You can create a Dynamic Link by using one of the methods below. Each method will return an instance of

Kreait\Firebase\DynamicLink.

1.9. Dynamic Links 41

Firebase Admin SDK for PHP

use use Kreait\Firebase\DynamicLink\CreateDynamicLink\FailedToCreateDynamicLink;

$url = 'https://www.example.com/some/path';

try {

$link = $dynamicLinks->createUnguessableLink($url);

$link = $dynamicLinks->createDynamicLink($url, CreateDynamicLink::WITH_

˓→UNGUESSABLE_SUFFIX);

$link = $dynamicLinks->createShortLink($url);

$link = $dynamicLinks->createDynamicLink($url, CreateDynamicLink::WITH_SHORT_

˓→SUFFIX);

} catch (FailedToCreateDynamicLink $e) {

echo $e->getMessage(); exit;

}

If createDynamicLink() is called without a second parameter, the Dynamic Link is created with an unguessable

sufﬁx.

Unguessable sufﬁxes have a length of 17 characters, short sufﬁxes a length of 4 characters. You can learn more about

the length of Dynamic Links in the ofﬁcial documentation.

The returned object will be an instance of Kreait\Firebase\DynamicLink with the following accessors:

$link->uri(); // Psr\Http\Message\UriInterface

$link->previewUri(); // Psr\Http\Message\UriInterface

$link->domain(); // string

$link->suffix(); // string

$link->hasWarnings(); // bool

$link->warnings(); // array

$uriString = (string) $link;

1.9.4 Create a short link from a long link

If you have a manually constructed link, you can convert it to a short link:

use Kreait\Firebase\DynamicLink\ShortenLongDynamicLink\FailedToShortenLongDynamicLink;

$longLink = 'https://example.page.link?link=https://domain.tld/some/path';

try {

$link = $dynamicLinks->shortenLongDynamicLink($longLink);

$link = $dynamicLinks->shortenLongDynamicLink($longLink,

˓→ShortenLongDynamicLink::WITH_UNGUESSABLE_SUFFIX);

$link = $dynamicLinks->shortenLongDynamicLink($longLink,

˓→ShortenLongDynamicLink::WITH_SHORT_SUFFIX);

} catch (FailedToShortenLongDynamicLink $e) {

echo $e->getMessage(); exit;

}

If shortenLongDynamicLink() is called without a second parameter, the Dynamic Link is created with an

unguessable sufﬁx.

42 Chapter 1. User Guide

Firebase Admin SDK for PHP

1.9.5 Get link statistics

You can use this REST API to get analytics data for each of your short Dynamic Links, whether created in the console

or programmatically.

Note: These statistics might not include events that have been logged within the last 36 hours.

use

˓→Kreait\Firebase\DynamicLink\GetStatisticsForDynamicLink\FailedToGetStatisticsForDynamicLink;

˓→

try {

$stats = $dynamicLinks->getStatistics('https://example.page.link/wXYZ');

$stats = $dynamicLinks->getStatistics('https://example.page.link/wXYZ', 14); //

˓→duration in days

} catch (FailedToGetStatisticsForDynamicLink $e) {

echo $e->getMessage(); exit;

}

If getStatistics() is called without a second parameter, stats will include the statistics of the past 7 days.

The returned object will be an instance of Kreait\Firebase\DynamicLink\DynamicLinkStatistics,

which currently only includes event statistics. You can access the raw returned data with $stats->rawData().

Event Statistics

Firebase Dynamic Links tracks the number of times each of your short Dynamic Links have been clicked, as well as

the number of times a click resulted in a redirect, app install, app ﬁrst-open, or app re-open, including the platform on

which that event occurred.

Each of the following methods returns a (ﬁltered) instance of Kreait\Firebase\DynamicLink\EventStatistics

which supports any combination of ﬁlters and is countable with count() or ->count() as shown below:

$eventStats = $stats->eventStatistics();

$allClicks = $eventStats->clicks();

$allRedirects = $eventStats->redirects();

$allAppInstalls = $eventStats->appInstalls();

$allAppFirstOpens = $eventStats->appFirstOpens();

$allAppReOpens = $eventStats->appReOpens();

$allAndroidEvents = $eventStats->onAndroid();

$allDesktopEvents = $eventStats->onDesktop();

$allIOSEvents = $eventStats->onIOS();

$clicksOnDesktop = $eventStats->clicks()->onDesktop();

$appInstallsOnAndroid = $eventStats->onAndroid()->appInstalls();

$appReOpensOnIOS = $eventStats->appReOpens()->onIOS();

$totalAmountOfClicks = count($eventStats->clicks());

$totalAmountOfAppFirstOpensOnAndroid = $eventStats->appFirstOpens()->onAndroid()->

˓→count();

$custom = $eventStats->filter(function (array $eventGroup) {

(continues on next page)

1.9. Dynamic Links 43

Firebase Admin SDK for PHP

(continued from previous page)

return $eventGroup['platform'] === 'CUSTOM_PLATFORM_THAT_THE_SDK_DOES_NOT_KNOW_YET

˓→';

});

1.9.6 Advanced usage

Using actions

You can fully customize the creation of Dynamic Links by building up a

Kreait\Firebase\DynamicLink\CreateDynamicLink action. The following code shows all avail-

able building components:

use Kreait\Firebase\DynamicLink\CreateDynamicLink;

$action = CreateDynamicLink::forUrl($url)

->withDynamicLinkDomain('https://example.page.link')

->withUnguessableSuffix() // default

// or

->withShortSuffix()

->withAnalyticsInfo(

AnalyticsInfo::new()

->withGooglePlayAnalyticsInfo(

GooglePlayAnalytics::new()

->withGclid('gclid')

->withUtmCampaign('utmCampaign')

->withUtmContent('utmContent')

->withUtmMedium('utmMedium')

->withUtmSource('utmSource')

->withUtmTerm('utmTerm')

)

->withItunesConnectAnalytics(

ITunesConnectAnalytics::new()

->withAffiliateToken('affiliateToken')

->withCampaignToken('campaignToken')

->withMediaType('8')

->withProviderToken('providerToken')

)

->withNavigationInfo(

NavigationInfo::new()

->withoutForcedRedirect() // default

// or

->withForcedRedirect()

)

->withIOSInfo(

IOSInfo::new()

->withAppStoreId('appStoreId')

->withBundleId('bundleId')

->withCustomScheme('customScheme')

->withFallbackLink('https://fallback.domain.tld')

->withIPadBundleId('iPadBundleId')

->withIPadFallbackLink('https://ipad-fallback.domain.tld')

)

->withAndroidInfo(

(continues on next page)

44 Chapter 1. User Guide

Firebase Admin SDK for PHP

(continued from previous page)

AndroidInfo::new()

->withFallbackLink('https://fallback.domain.tld')

->withPackageName('packageName')

->withMinPackageVersionCode('minPackageVersionCode')

)

->withSocialMetaTagInfo(

SocialMetaTagInfo::new()

->withDescription('Social Meta Tag description')

->withTitle('Social Meta Tag title')

->withImageLink('https://domain.tld/image.jpg')

);

$link = $dynamicLinks->createDynamicLink($action);

Using parameter arrays

If you prefer using a parameter array to conﬁgure a Dynamic Link, or if this SDK doesn’t yet have support for a given

new option, you can pass an array to the createDynamicLink() method. As the parameters will not be processed

or validated by the SDK, you have to make sure that the parameter structure matches the one described in the API

Reference Documentation

use use Kreait\Firebase\DynamicLink\CreateDynamicLink\FailedToCreateDynamicLink;

$parameters = [

'dynamicLinkInfo' => [

'domainUriPrefix' => 'https://example.page.link',

'link' => 'https://domain.tld/some/path',

'suffix' => ['option' => 'SHORT'],

];

try {

$link = $dynamicLinks->createDynamicLink($parameters);

} catch (FailedToCreateDynamicLink $e) {

echo $e->getMessage(); exit;

}

1.10 Remote Conﬁg

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

Firebase Remote Conﬁg 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 Conﬁg, you create in-app default values that control

the behavior and appearance of your app.

Before you start, please read about Firebase Remote Conﬁg in the ofﬁcial documentation:

• Firebase Remote Conﬁg

1.10. Remote Conﬁg 45

Firebase Admin SDK for PHP

1.10.1 Before you begin

For Firebase projects created before the March 7, 2018 release of the Remote Conﬁg REST API, you must enable the

API in the Google APIs console.

1. Open the Firebase Remote Conﬁg 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 Conﬁg API page.

1.10.2 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');

1.10.3 Get the Remote Conﬁg

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

// Added in 4.29.0

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

1.10.4 Create a new Remote Conﬁg

use Kreait\Firebase\RemoteConfig;

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

1.10.5 Add a condition

46 Chapter 1. User Guide

Firebase Admin SDK for PHP

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);

1.10.6 Add a parameter

use Kreait\Firebase\RemoteConfig;

$welcomeMessageParameter = Parameter::named('welcome_message')

->withDefaultValue('Welcome!')

->withDescription('This is a welcome message') // optional

;

1.10.7 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 ﬁrst.

1.10.8 Validation

Usually, the SDK will protect you from creating an invalid Remote Conﬁg template in the ﬁrst 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();

}

1.10. Remote Conﬁg 47

Firebase Admin SDK for PHP

Note: The ValidationFailed exception extends Kreait\Firebase\Exception\RemoteConfigException,

so you can safely use the more generic exception type as well.

1.10.9 Publish the Remote Conﬁg

use Kreait\Firebase\Exception\RemoteConfigException

try {

$remoteConfig->publish($template);

} catch (RemoteConfigException $e) {

echo $e->getMessage();

}

1.10.10 Remote Conﬁg history

Since August 23, 2018, Firebase provides a change history for your published Remote conﬁgs.

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

You can ﬁlter the results of RemoteConfig::listVersions():

48 Chapter 1. User Guide

Firebase Admin SDK for PHP

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 speciﬁc version

$version = $remoteConfig->getVersion($versionNumber);

Rollback to a version

$template = $remoteConfig->rollbackToVersion($versionNumber);

1.11 Framework Integrations

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

1.11.1 Laravel

kreait/laravel-ﬁrebase

1.11. Framework Integrations 49

Firebase Admin SDK for PHP

1.11.2 Symfony

kreait/ﬁrebase-bundle

1.11.3 CodeIgniter

tatter/ﬁrebase

1.12 Tutorials

You can ﬁnd an example project implementing the Firebase Admin SDK for PHP at https://github.com/jeromegamez/

ﬁrebase-php-examples .

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

1.12.1 Articles

• How to integrate Laravel with Google Firebase by Javier Núñez (English, April 2019)

• Integrate Firebase With PHP and Optimize Your Real Time Communication by Shahroze Nawaz (English,

November 2018)

• Connect Laravel with Firebase Real Time Database by Pardeep Kumar (English, March 2018)

1.12.2 Videos

• Firebase for Web | PHP Tutorial by Umar Hameed (Hindi/Urdu, January 2019)

• Firebase and PHP by Arthur Mann (English, August 2018)

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.

1.13 Troubleshooting

1.13.1 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.

50 Chapter 1. User Guide

Firebase Admin SDK for PHP

1.13.2 Class ‘Kreait\Firebase\ . . . ’ not found

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

1.13.3 Call to undeﬁned function openssl_sign()

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

1.13.4 cURL error XX: . . .

If you receive a cURL error XX: ..., make sure that you have a current CA Root Certiﬁcates 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 ﬁle given in the default_cert_file ﬁeld actually exists. Create a backup of the ﬁle, 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 conﬁgure the curl.cainfo setting in your php.ini:

[curl]

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

1.13.5 ID Tokens are issued in the future

When ID Token veriﬁcation 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:

1.13. Troubleshooting 51

Firebase Admin SDK for PHP

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;

}

1.13.6 “403 Forbidden” Errors

Under the hood, a Firebase project is actually a Google Cloud project with pre-deﬁned and pre-allocated permissions

and resources.

When Google adds features to its product line, it is possible that you have to manually conﬁgure 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:

• Firebase Services: https://console.cloud.google.com/apis/library/ﬁrebase.googleapis.com

• Cloud Messaging (FCM): https://console.cloud.google.com/apis/library/fcm.googleapis.com

• FCM Registration API: https://console.cloud.google.com/apis/library/fcmregistrations.googleapis.com

• Dynamic Links: https://console.cloud.google.com/apis/library/ﬁrebasedynamiclinks.googleapis.com

• Firestore: https://console.cloud.google.com/apis/library/ﬁrestore.googleapis.com

• Realtime Database Rules: https://console.cloud.google.com/apis/library/ﬁrebaserules.googleapis.com

• Remote Conﬁg: https://console.cloud.google.com/apis/library/ﬁrebaseremoteconﬁg.googleapis.com

• Storage: https://console.cloud.google.com/apis/library/storage-component.googleapis.com

Please also make sure that the Service Account you are using for your project has all necessary roles and permissions

as described in the ofﬁcial documentation at Manage project access with Firebase IAM.

1.13.7 Proxy conﬁguration

If you need to access the Firebase/Google APIs through a proxy, you can conﬁgure the SDK to use one via Guzzle’s

proxy conﬁguration:

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

1.13.8 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 conﬁg:

52 Chapter 1. User Guide

Firebase Admin SDK for PHP

$factory = $factory->withEnabledDebug();

1.13. Troubleshooting 53