Firebase Admin SDK for PHP

https://firebase-php.readthedocs.io/latest
Admin
Firebase Admin SDK for PHP enables access to Firebase services including authentication, Cloud...
Tokens:27,120
Snippets:333
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Firebase Admin SDK via Composer

Source: https://firebase-php.readthedocs.io/latest/index.html

Use this command to install the SDK as a dependency in your PHP project.

```bash
composer require "kreait/firebase-php:^8.0"
```

--------------------------------

### Formatting Token Response

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Example structure for a token response returned to clients.

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

--------------------------------

### Example CA Certificate Output

Source: https://firebase-php.readthedocs.io/latest/troubleshooting.html

This represents the expected structure returned by openssl_get_cert_locations().

```text
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) ""
}
```

--------------------------------

### Comprehensive error handling example

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Demonstrates a robust pattern for catching multiple specific messaging exceptions in a single try-catch block.

```php
use Kreait\Firebase\Exception\Messaging as MessagingErrors;
use Kreait\Firebase\Exception\MessagingException;

try {
    $messaging->send($message);
} catch (MessagingErrors\NotFound $e) {
    echo 'The target device could not be found.';
} catch (MessagingErrors\InvalidMessage $e) {
    echo 'The given message is malformatted.';
} catch (MessagingErrors\ServerUnavailable $e) {
    $retryAfter = $e->retryAfter();

    echo 'The FCM servers are currently unavailable. Retrying at '.$retryAfter->format(\DATE_ATOM);

    // This is just an example. Using `sleep()` will block your script execution, don't do this.
    while ($retryAfter <= new DateTimeImmutable()) {
        sleep(1);
    }

    $messaging->send($message);
} catch (MessagingErrors\ServerError $e) {
    echo 'The FCM servers are down.';
} catch (MessagingException $e) {
    // Fallback handling
    echo 'Unable to send message: '.$e->getMessage();
}
```

--------------------------------

### Install Firestore dependency

Source: https://firebase-php.readthedocs.io/latest/cloud-firestore.html

Add the required google/cloud-firestore package to your project dependencies via Composer.

```bash
composer require google/cloud-firestore
```

--------------------------------

### Get Firestore database instance

Source: https://firebase-php.readthedocs.io/latest/cloud-firestore.html

Retrieve the database instance from the Firestore client.

```php
$database = $firestore->database();
```

--------------------------------

### Set Message Priority

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Example of setting global message priority and overriding it with specific APNS configuration.

```php
$message = CloudMessage::new()
    ->withNotification([
        'title' => 'If you had an iOS device…',
        'body' => '… you would have received a very important message'
    ])
    ->withLowestPossiblePriority()
    ->withApnsConfig(
        ApnsConfig::new()
            ->withImmediatePriority()
            ->withNotification([
                'title => 'A very important message…',
                'body' => '… that requires your immediate attention.'
            ])
    )
;
```

--------------------------------

### Check cURL version

Source: https://firebase-php.readthedocs.io/latest/troubleshooting.html

Use this snippet to verify the currently installed cURL version in your PHP environment.

```php
echo curl_version()['version']; exit;
```

--------------------------------

### Get Specific Remote Config Version

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Retrieves a specific version object by its version number.

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

--------------------------------

### Get the Remote Config

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Methods to retrieve the current Remote Config template or a specific version.

```APIDOC
## Get the Remote Config

### Description
Retrieves the current Remote Config template or a template associated with a specific version number.

### Methods
- `$remoteConfig->get()`: Returns the current `Kreait\Firebase\RemoteConfig\Template`.
- `$remoteConfig->get($versionNumber)`: Returns a `Kreait\Firebase\RemoteConfig\Template` for the specified version.
```

--------------------------------

### Retrieve Child Keys

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Convenience method to get an array of key names for a reference's children.

```php
$database->getReference('currencies')->getChildKeys(); // returns an array of key names
```

--------------------------------

### Initialize Realtime Database

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Create a database instance from the factory.

```php
$database = $factory->createDatabase();
```

--------------------------------

### Configure SDK with Service Account File

Source: https://firebase-php.readthedocs.io/latest/setup.html

Manually provide the path to a JSON service account key file to the factory when auto-discovery is not used.

```php
use Kreait\Firebase\Factory;

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

--------------------------------

### Initialize the Storage component

Source: https://firebase-php.readthedocs.io/latest/cloud-storage.html

Create a storage instance using the factory object.

```php
$storage = $factory->createStorage();
```

--------------------------------

### Set Realtime Database Emulator Environment Variable

Source: https://firebase-php.readthedocs.io/latest/testing.html

Enable the SDK to connect to the Realtime Database emulator by setting the host environment variable.

```bash
$ export FIREBASE_DATABASE_EMULATOR_HOST="localhost:9100"
```

--------------------------------

### Initialize Firestore component

Source: https://firebase-php.readthedocs.io/latest/cloud-firestore.html

Create a Firestore instance using the factory.

```php
$firestore = $factory->createFirestore();
```

--------------------------------

### Initialize Remote Config

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Create a Remote Config instance using the factory.

```php
$remoteConfig = $factory->createRemoteConfig();
```

--------------------------------

### Initialize the Auth component

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Use this snippet to create an instance of the Auth component from the factory.

```php
$auth = $factory->createAuth();
```

--------------------------------

### Configure default storage bucket

Source: https://firebase-php.readthedocs.io/latest/cloud-storage.html

Override the default bucket name during factory initialization if the standard <project-id>.appspot.com format is not desired.

```php
use Kreait\Firebase\Factory;

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

--------------------------------

### Database Initialization and Data Retrieval

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Methods for initializing the database component and retrieving data snapshots from specific paths.

```APIDOC
## Database Initialization

### Description
Initializes the Realtime Database component from the factory.

### Method
`$factory->createDatabase()`

## Retrieving Data

### Description
Accesses a node in the database via a Reference and retrieves its value or snapshot.

### Methods
- `$database->getReference('path/to/child/location')` - Returns a Reference object for the specified path.
- `$reference->getSnapshot()` - Retrieves a Database Snapshot for the reference.
- `$reference->getValue()` - Retrieves the value at the reference location directly.
```

--------------------------------

### Configure Project ID and Database URI

Source: https://firebase-php.readthedocs.io/latest/setup.html

Manually set the project ID and database URI when using credentials that do not include project information.

```php
use Kreait\Firebase\Factory;

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

--------------------------------

### Initialize the Messaging component

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Create a messaging instance from the factory to begin sending messages.

```php
$messaging = $factory->createMessaging();
```

--------------------------------

### Initializing the Remote Config component

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

How to initialize the Remote Config component using the factory.

```APIDOC
## Initializing the Remote Config component

### Description
Initializes the Remote Config component using the Firebase factory.

### Usage
```php
$remoteConfig = $factory->createRemoteConfig();
```
```

--------------------------------

### Set Auth Emulator Environment Variable

Source: https://firebase-php.readthedocs.io/latest/testing.html

Enable the SDK to connect to the Auth emulator by setting the host environment variable.

```bash
$ export FIREBASE_AUTH_EMULATOR_HOST="localhost:9099"
```

--------------------------------

### Configure Firestore client options

Source: https://firebase-php.readthedocs.io/latest/cloud-firestore.html

Pass additional configuration options to the Firestore client during factory initialization.

```php
use Kreait\Firebase\Factory;

$factory = new Factory();

$firestore = $factory
    ->withFirestoreClientConfig([...])
    ->createFirestore();
```

--------------------------------

### Initialize Firebase Admin SDK

Source: https://firebase-php.readthedocs.io/latest/index.html

Configure the factory with your service account credentials and database URI to access Firebase services.

```php
use Kreait\Firebase\Factory;

$factory = (new Factory)
    ->withServiceAccount('/path/to/firebase_credentials.json')
    ->withDatabaseUri('https://my-project-default-rtdb.firebaseio.com');

$auth = $factory->createAuth();
$realtimeDatabase = $factory->createDatabase();
$cloudMessaging = $factory->createMessaging();
$remoteConfig = $factory->createRemoteConfig();
$cloudStorage = $factory->createStorage();
$firestore = $factory->createFirestore();
```

--------------------------------

### Define User Queries with Objects and Arrays

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Demonstrates how to configure sorting, ordering, offset, and limits using either a UserQuery object or an associative array.

```php
use Kreait\Firebase\Auth\UserQuery;

# Building a user query object
$userQuery = UserQuery::all()
    ->sortedBy(UserQuery::FIELD_USER_EMAIL)
    ->inDescendingOrder()
    // ->inAscendingOrder() # this is the default
    ->withOffset(1)
    ->withLimit(499); # The maximum supported limit is 500

# Using an array
$userQuery = [
    'sortBy' => UserQuery::FIELD_USER_EMAIL,
    'order' => UserQuery::ORDER_DESC,
    // 'order' => UserQuery::ORDER_DESC # this is the default
    'offset' => 1,
    'limit' => 499, # The maximum supported limit is 500
];
```

--------------------------------

### Initialize App Check

Source: https://firebase-php.readthedocs.io/latest/app-check.html

Create an instance of the App Check component using the factory.

```php
$appCheck = $factory->createAppCheck();
```

--------------------------------

### Retrieve App Instance Information

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Fetches detailed information about an app instance using its registration token. The raw data structure varies by platform.

```php
$registrationToken = '...';

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

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

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

--------------------------------

### Create a new Remote Config

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

How to instantiate a new Remote Config template.

```APIDOC
## Create a new Remote Config

### Description
Creates a new instance of a Remote Config template.

### Usage
```php
use Kreait\Firebase\RemoteConfig;

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

--------------------------------

### Configure End User Credentials

Source: https://firebase-php.readthedocs.io/latest/setup.html

Use this when working with local application default credentials. Suppress warnings and explicitly define the project ID to ensure correct authentication.

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

--------------------------------

### Create New Remote Config Template

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Initialize a new Remote Config template object.

```php
use Kreait\Firebase\RemoteConfig;

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

--------------------------------

### Configure Realtime Database URI

Source: https://firebase-php.readthedocs.io/latest/setup.html

Specify the database URI manually if the default automatic generation is not desired.

```php
use Kreait\Firebase\Factory;

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

--------------------------------

### Configure Notification Sounds

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Shows how to enable default sounds and specify custom sound files for APNS configurations.

```php
$message = CloudMessage::new()
    ->withNotification(['title' => 'Notification title', 'body' => 'Notification body'])
    ->withDefaultSounds() // Enables default notifications sounds on iOS and Android devices.
    ->withApnsConfig(
        ApnsConfig::new()
            ->withSound('bingbong.aiff')
            ->withBadge(1)
    )
;
```

--------------------------------

### Retrieve Data from Reference

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Fetch data using snapshots or direct value retrieval methods.

```php
$snapshot = $reference->getSnapshot();

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

--------------------------------

### Configure FCM Options

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Demonstrates how to set analytics labels using either the FcmOptions object or an associative array.

```php
use Kreait\Firebase\Messaging\FcmOptions;

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

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

--------------------------------

### Create and modify a notification

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Demonstrates creating a notification instance from an array or factory method, and using immutable with-methods to update properties.

```php
use Kreait\Firebase\Messaging\Notification;

$title = 'My Notification Title';
$body = 'My Notification Body';
$imageUrl = 'https://example.com/image.jpg';

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

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

$changedNotification = $notification
    ->withTitle('Changed title')
    ->withBody('Changed body')
    ->withImageUrl('https://example.com/image.jpg');
```

--------------------------------

### Generate and Send Email Sign-in Links

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Use these methods to generate a sign-in link or send it directly to the user's email. Requires an ActionCodeSettings object to define the redirect URL.

```php
$link = $auth->getSignInWithEmailLink($email, $actionCodeSettings);

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

--------------------------------

### getAppInstance(string $registrationToken)

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Retrieves information about an app instance associated with a specific registration token.

```APIDOC
## getAppInstance(string $registrationToken)

### Description
Retrieves current information about an app instance by passing a registration token. The returned object provides access to the raw data from the Firebase API.

### Parameters
- **registrationToken** (string) - Required - The registration token of the application instance.

### Returns
- **Kreait\Firebase\Messaging\AppInstance** - An object representing the app instance.
```

--------------------------------

### Work with Database Snapshots

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Access immutable copies of data at a specific location.

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

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

--------------------------------

### Add a Remote Config Parameter

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Create a new parameter with a default value and description.

```php
use Kreait\Firebase\RemoteConfig;
use Kreait\Firebase\RemoteConfig\ParameterValueType;

$welcomeMessageParameter = RemoteConfig\Parameter::named('welcome_message')
        ->withDefaultValue('Welcome!')
        ->withDescription('This is a welcome message') // optional
        ->withValueType(ParameterValueType $valueType): self
;
```

--------------------------------

### Sign In with Email and Password

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Authenticates a user using their email and clear-text password.

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

--------------------------------

### Configure Realtime Database Emulator in firebase.json

Source: https://firebase-php.readthedocs.io/latest/testing.html

Define the port for the Realtime Database emulator in the project's firebase.json file.

```json
{
  "emulators": {
    "database": {
      "port": 9100
    }
  }
}
```

--------------------------------

### Configure Tenant-Aware Authentication

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Use the factory to create an Auth instance scoped to a specific tenant ID. The tenant ID must be enabled in the Google Cloud Identity Platform project.

```php
$tenantUnawareAuth = $factory->createAuth();

$tenantAwareAuth = $factory
    ->withTenantId('my-tenant-id')
    ->createAuth();
```

--------------------------------

### Construct and send a Cloud Message

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Build a message with notification, data, and target identifiers, then send it via the messaging instance.

```php
use Kreait\Firebase\Messaging\CloudMessage;

$message = CloudMessage::new()
    ->withNotification(Notification::create('Title', 'Body'))
    ->withData(['key' => 'value'])
    ->withToken('...')
    // ->withTopic('...')
    // ->withCondition('...')
;

$messaging->send($message);
```

--------------------------------

### Sign In with IdP Credentials

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Authenticates a user using credentials from external identity providers.

```php
$signInResult = $auth->signInWithIdpAccessToken($provider, string $accessToken, $redirectUrl = null, ?string $oauthTokenSecret = null, ?string $linkingIdToken = null, ?string $rawNonce = null);

$signInResult = $auth->signInWithIdpIdToken($provider, $idToken, $redirectUrl = null, ?string $linkingIdToken = null, ?string $rawNonce = null);
```

--------------------------------

### createUser(array $properties)

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Creates a new user and handles potential email-related exceptions.

```APIDOC
## createUser(array $properties)

### Description
Creates a new user. Throws `Kreait\Firebase\Exception\Auth\EmailExists` if the email is already in use.

### Parameters
- **$properties** (array) - Required - User attributes such as 'email'.
```

--------------------------------

### Specify a custom UID during user creation

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Allows setting a custom UID for a new user instead of relying on the automatically generated one.

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

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

--------------------------------

### List Remote Config Versions

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Retrieves version history as a Generator to optimize memory usage for large datasets.

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

--------------------------------

### List Users with Generator

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Retrieves users in batches using a generator to optimize memory usage.

```php
$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));
```

--------------------------------

### Create Parameter Groups

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Organize related parameters into named groups within the Remote Config template.

```php
use Kreait\\\Firebase\\\RemoteConfig;

$uiColors = RemoteConfig\\\ParameterGroup::named('UI Colors')
    ->withDescription('Remote configurable UI colors')
    ->withParameter(RemoteConfig\\\Parameter::named('Primary Color')->withDefaultValue('blue'))
    ->withParameter(RemoteConfig\\\Parameter::named('Secondary Color')->withDefaultValue('red'))
;

$template = $template->withParameterGroup($parameterGroup);
```

--------------------------------

### Configure HTTP Client Options

Source: https://firebase-php.readthedocs.io/latest/setup.html

Customize Guzzle HTTP client behavior such as timeouts, proxies, and custom handlers before creating services.

```php
use Kreait\Firebase\Http\HttpClientOptions;

$options = HttpClientOptions::default();

// Set the maximum amount of seconds (float) that can pass before
// a request is considered timed out
// (default: indefinitely)
$options = $options->withTimeOut(3.5);

// Use a proxy that all API requests should be passed through.
// (default: none)
$options = $options->withProxy('tcp://<host>:<port>');

// Use a custom handler
$options = $options->withGuzzleHandler(...);

$factory = $factory->withHttpClientOptions($options);

// Newly created services will now use the new HTTP options
$realtimeDatabase = $factory->createDatabase();
```

--------------------------------

### Filter Remote Config Versions

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Demonstrates filtering version history using the FindVersions builder or an associative array.

```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";
}
```

--------------------------------

### Execute User Query

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Executes the defined query against the authentication service.

```php
$users = $auth->queryUsers($userQuery);
```

--------------------------------

### Configure Database Rules

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Manage security rules using the RuleSet class, including default, public, private, and custom configurations.

```php
use Kreait\Firebase\Database\RuleSet;

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

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

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

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

$database->updateRules($ruleSet);

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

--------------------------------

### Order Data by Key

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Order children by their key in ascending order.

```php
$database->getReference('currencies')
    // order the reference's children by their key in ascending order
    ->orderByKey()
    ->getSnapshot();
```

--------------------------------

### Configure Auth Emulator in firebase.json

Source: https://firebase-php.readthedocs.io/latest/testing.html

Define the port for the Auth emulator in the project's firebase.json file.

```json
{
  "emulators": {
    "auth": {
      "port": 9099
    }
  }
}
```

--------------------------------

### Sign In with Email and Oob Code

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Authenticates a user using an email and an out-of-band code.

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

--------------------------------

### Downscope to Unauthenticated Client

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Pass null to the database auth variable override to treat the SDK instance as an unauthenticated client.

```php
$database = $factory
    ->withDatabaseAuthVariableOverride(null)
    ->createDatabase();

// $database now only has access to public resources
```

--------------------------------

### Access Remote Config Version Properties

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Lists the available methods to retrieve metadata from a Version object.

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

--------------------------------

### Retrieve user information by identifier

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Fetches a user record using UID, email, phone number, or federated provider UID. Throws a UserNotFound exception if the user does not exist.

```php
try {
    $user = $auth->getUser('some-uid');
    $user = $auth->getUserByEmail('user@example.com');
    $user = $auth->getUserByPhoneNumber('+49-123-456789');
    // For `getUserByProviderUid()` please see the section below.
    $user = $auth->getUserByProviderUid('google.com', 'google-uid');
} catch (\Kreait\Firebase\Exception\Auth\UserNotFound $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Filter User Queries

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Shows how to apply filters for email, phone number, or UID. Note that only one filter can be active at a time.

```php
use Kreait\Firebase\Auth\UserQuery;

$userQuery = UserQuery::all()->withFilter(UserQuery::FILTER_EMAIL, '<email>');
$userQuery = UserQuery::all()->withFilter(UserQuery::FILTER_PHONE_NUMBER, '<phone number>');
$userQuery = UserQuery::all()->withFilter(UserQuery::FILTER_UID, '<uid>');

$userQuery = ['filter' => [UserQuery::FILTER_EMAIL => '<email>'];
$userQuery = ['filter' => [UserQuery::FILTER_PHONE_NUMBER => '<email>'];
$userQuery = ['filter' => [UserQuery::FILTER_UID => '<email>'];
```

--------------------------------

### Sign In with a Custom Token

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Authenticates a user using a custom token.

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

--------------------------------

### Access storage buckets

Source: https://firebase-php.readthedocs.io/latest/cloud-storage.html

Retrieve the underlying storage client or specific buckets by name.

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

--------------------------------

### Write to lists

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Use push() to append data to a list with a unique, chronologically ordered key. The returned reference allows access to the generated key via getKey().

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

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

--------------------------------

### Set Guzzle Configuration Options

Source: https://firebase-php.readthedocs.io/latest/setup.html

Apply additional Guzzle-specific configuration options to the HTTP client.

```php
use Kreait\Firebase\Http\HttpClientOptions;

$options = HttpClientOptions::default()
    ->withGuzzleConfigOption('single', 'value')
    ->withGuzzleConfigOptions([
        'first' => 'value',
        'second' => 'value',
    ]);
```

--------------------------------

### Handle NotFound exceptions

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Catch errors when a registration token is valid but not found, and retrieve the specific token that caused the issue.

```php
use Kreait\Firebase\Exception\Messaging\NotFound;

try {
    $messaging->send($message);
} catch (NotFound $e) {
    echo $e->getMessage();
    print_r($e->errors());
    // If the message was send to a token, you can retrieve the unknown token
    echo $e->token();
}
```

--------------------------------

### Enable user account

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Re-enables a previously disabled user account.

```php
$uid = 'some-uid';

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

--------------------------------

### Retrieve Database Reference

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Access a specific node in the database using a path.

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

--------------------------------

### Retrieve Topic Subscriptions

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Fetches all topic subscriptions for a specific app instance and iterates through them.

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

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

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

--------------------------------

### Configure Android-specific settings

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Defines Android-specific configuration including TTL, priority, and notification appearance.

```php
use Kreait\Firebase\Messaging\AndroidConfig;

$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',
        'sound' => 'default',
    ],
]);

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

--------------------------------

### Configure WebPush-specific settings

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Defines WebPush configuration including notification content and FCM options like links.

```php
use Kreait\Firebase\Messaging\WebPushConfig;

$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.example/icon.png',
    ],
    'fcm_options' => [
        'link' => 'https://my-server.example/some-page',
    ],
]);

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

--------------------------------

### Define Action Code Settings

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Configure optional settings for email action links, such as continue URLs and mobile app handling.

```php
$actionCodeSettings = [
    'continueUrl' => 'https://www.example.com/checkout?cartId=1234',
    'handleCodeInApp' => true,
    'androidPackageName' => 'com.example.android',
    'androidMinimumVersion' => '12',
    'androidInstallApp' => true,
    'iOSBundleId' => 'com.example.ios',
];
```

--------------------------------

### Send messages to topics

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Constructs a CloudMessage targeting a topic using either the fluent builder interface or an array configuration, then sends it via the messaging service.

```php
use Kreait\Firebase\Exception\MessagingException;
use Kreait\Firebase\Messaging\CloudMessage;

$topic = 'a-topic';

$message = CloudMessage::new()
    ->withNotification($notification) // optional
    ->withData($data) // optional
    ->withTopic($topic)
;

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

try {
    $result = $messaging->send($message);
    // $result = ['name' => 'projects/<project-id>/messages/6810356097230477954']
} catch (MessagingException $e) {
    // ...
}
```

--------------------------------

### Filter results with startAt

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Returns items greater than or equal to the specified value after ordering.

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

--------------------------------

### Add a Remote Config Condition

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Define conditions using expressions and optional tag colors, then add them to a Remote Config template.

```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

$frenchLanguageCondition = Condition::named('lang_french')
    ->withExpression("device.language in ['fr', 'fr_CA', 'fr_CH']")
    ->withTagColor(TagColor::GREEN);

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

$conditionNames = $template->conditionNames();
// Returns ['lang_german', 'lang_french']
```

--------------------------------

### Handle email existence errors

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Catches specific exceptions when creating a user with an existing email or signing in with an unregistered email.

```php
try {
    $user = $auth->createUser([
        'email' => $email,
    ]);
} catch (\Kreait\Firebase\Exception\Auth\EmailExists $e) {
    echo $e->getMessage(); // "The email address is already in use by another account"
}

try {
    $signInResult = $auth->signInWithEmailAndPassword($email, $password);
} catch (\Kreait\Firebase\Exception\Auth\EmailNotFound $e) {
    echo $e->getMessage(); // "There is no user record corresponding to this identifier. The user may have been deleted."
}
```

--------------------------------

### RemoteConfig::listVersions

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Retrieves a list of Remote Config versions with optional filtering.

```APIDOC
## Method: RemoteConfig::listVersions

### Description
Returns a generator of version objects representing the change history of Remote Config templates.

### Parameters
- **query** (array|FindVersions) - Optional - Filtering criteria including startingAt, endingAt, upToVersion, pageSize, and limit.
```

--------------------------------

### Define Conditional Values

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Create conditions and conditional values to serve specific content based on device language.

```php
use Kreait\\\Firebase\\\RemoteConfig;

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

$germanWelcomeMessage = RemoteConfig\\\ConditionalValue::basedOn($germanLanguageCondition)->withValue('Willkommen!');

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

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

--------------------------------

### Implement PSR-6 Caching

Source: https://firebase-php.readthedocs.io/latest/setup.html

Provide a PSR-6 cache implementation to the factory to persist authentication tokens, JWKS, and verified tokens across processes.

```php
use Symfony\Component\Cache\Simple\FilesystemCache;

// One Cache instance for all components
$factory = $factory->withDefaultCache(new FilesystemCache());

// Cache used for authentication tokens, so that they requests don't have to be re-authenticated
$factory = $factory->withAuthTokenCache(new FilesystemCache());

// Cache used to store JWKS (JSON Web Key Sets), so that they don't have to be fetched again
$factory = $factory->withKeySetCache(new FilesystemCache());

// Cache used to store verified ID tokens and session cookies, so that they don't have to be verified again
$factory = $factory->withVerifierCache(new FilesystemCache());
```

--------------------------------

### Handle ServerError and ServerUnavailable exceptions

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Distinguish between temporary server unavailability and permanent server errors.

```php
use Kreait\Firebase\Exception\Messaging\ServerError;
use Kreait\Firebase\Exception\Messaging\ServerUnavailable;

try {
    $messaging->send($message);
} catch (ServerUnavailable $e) {
    echo 'The FCM servers are currently unavailable: '.$e->getMessage();
    print_r($e->errors());
    $retryAfter= $e->retryAfter();
} catch (ServerError $e) {
    echo 'The FCM servers are broken: '.$e->getMessage();
    print_r($e->errors());
}
```

--------------------------------

### Validate Remote Config Template

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Use this to verify a template before publishing. Catches ValidationFailed exceptions to handle invalid configurations.

```php
use Kreait\Firebase\Exception\RemoteConfig\ValidationFailed;

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

--------------------------------

### Create Custom Tokens

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Generate custom tokens for users or devices using a unique UID. Additional claims can be included to pass custom data to Security Rules.

```php
$uid = 'some-uid';

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

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

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

$customTokenString = $customToken->toString();
```

--------------------------------

### Retrieve multiple users

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Fetches multiple user records by an array of UIDs. Non-existent users return null in the result set.

```php
$users = $auth->getUsers(['some-uid', 'another-uid', 'non-existing-uid']);
```

```text
[
    'some-uid' => <UserRecord>,
    'another-uid' => <UserRecord>,
    'non-existing-uid' => null
]
```

--------------------------------

### Retrieve Remote Config Template

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Fetch the current Remote Config template or a specific version by its version number.

```php
$template = $remoteConfig->get(); // Returns a Kreait\Firebase\RemoteConfig\Template
$version = $template->version(); // Returns a Kreait\Firebase\RemoteConfig\Version
$template = $remoteConfig->get($version->versionNumber()); // Returns a Kreait\Firebase\RemoteConfig\Template with the specified version
```

--------------------------------

### Database Queries and Ordering

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Methods for filtering and ordering data retrieved from the Realtime Database.

```APIDOC
## Querying Data

### Description
Methods to filter and order results from the database.

### Methods
- `->shallow()` - Limits the depth of data returned at a location.
- `->getChildKeys()` - Retrieves an array of key names for a reference's children.
- `->orderByKey()` - Orders children by their key in ascending order.
- `->orderByValue()` - Orders children by their value in ascending order (requires index).
- `->orderByChild('field')` - Orders children by the value of a specific field (requires index).
```

--------------------------------

### Handle SDK errors with try/catch

Source: https://firebase-php.readthedocs.io/latest/troubleshooting.html

Use this pattern to catch Firebase-specific exceptions and general PHP throwables when performing SDK operations.

```php
use Kreait\Firebase\Exception\FirebaseException;
use Throwable;

try {
    // The operation you want to perform
    echo 'OK';
} catch (FirebaseException $e} {
    echo 'An error has occurred while working with the SDK: '.$e->getMessage;
} catch (Throwable $e) {
    echo 'A not-Firebase specific error has occurred: '.$e->getMessage;
}
```

--------------------------------

### Topic Management

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Methods for managing device subscriptions to messaging topics.

```APIDOC
## Topic Subscription Methods

### Methods
- **$messaging->subscribeToTopic($topic, $registrationTokenOrTokens)**
- **$messaging->subscribeToTopics($topics, $registrationTokenOrTokens)**
- **$messaging->unsubscribeFromTopic($topic, $registrationTokenOrTokens)**
- **$messaging->unsubscribeFromTopics($topics, $registrationTokenOrTokens)**
- **$messaging->unsubscribeFromAllTopics($registrationTokenOrTokens)**

### Description
Manages device subscriptions to one or more topics. Note that a maximum of 1,000 registration tokens can be processed in a single request.
```

--------------------------------

### $auth->enableUser($uid)

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Enables a previously disabled user account.

```APIDOC
## $auth->enableUser($uid)

### Description
Enables the specified user account.

### Parameters
- **uid** (string) - Required - The unique identifier of the user.
```

--------------------------------

### Verify Tokens with Replay Protection

Source: https://firebase-php.readthedocs.io/latest/app-check.html

Perform an additional check to ensure a token has not been consumed, using the transitional AppCheckWithReplayProtection contract.

```php
use Kreait\Firebase\Contract\AppCheck;
use Kreait\Firebase\Contract\AppCheckWithReplayProtection;
use Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckReplayProtection;

/** @var AppCheck&AppCheckWithReplayProtection $appCheck */
$verification = null;

try {
    $verification = $appCheck->verifyTokenWithReplayProtection($appCheckTokenString);
} catch (FailedToVerifyAppCheckReplayProtection $e) {
    // The token could not be consumed for replay protection.
}

if ($verification?->alreadyConsumed === true) {
    // Reject the request as a replay attempt.
}
```

--------------------------------

### createUser

Source: https://firebase-php.readthedocs.io/latest/user-management.html

Creates a new Firebase Authentication user.

```APIDOC
## $auth->createUser(array|CreateUser $properties)

### Description
Creates a new user account with the provided properties.

### Parameters
- **properties** (array|CreateUser) - Required - An array or object containing user profile information.

### Properties
- **uid** (string) - Optional - Custom UID (1-128 chars).
- **email** (string) - Optional - User email.
- **emailVerified** (boolean) - Optional - Email verification status.
- **phoneNumber** (string) - Optional - E.164 phone number.
- **password** (string) - Optional - Raw password (min 6 chars).
- **displayName** (string) - Optional - User display name.
- **photoURL** (string) - Optional - User photo URL.
- **disabled** (boolean) - Optional - Account disabled status.

### Response
- **UserRecord** (object) - The newly created user record.
```

--------------------------------

### RemoteConfig\Parameter

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Methods for creating and configuring Remote Config parameters.

```APIDOC
## Parameter::named(string $name)

### Description
Creates a new parameter instance with a specific name.

### Methods
- **withDefaultValue(string $value)**: Sets the default value for the parameter.
- **withDescription(string $description)**: Sets an optional description for the parameter.
- **withValueType(ParameterValueType $valueType)**: Sets the data type for the parameter (STRING, BOOL, NUMBER, or JSON).
```

--------------------------------

### Sign In with a Refresh Token

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Authenticates a user using a refresh token.

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

--------------------------------

### topicSubscriptions()

Source: https://firebase-php.readthedocs.io/latest/cloud-messaging.html

Retrieves all topic subscriptions for a given app instance.

```APIDOC
## topicSubscriptions()

### Description
Retrieves all topic subscriptions associated with an AppInstance object.

### Returns
- **Kreait\Firebase\Messaging\TopicSubscriptions** - A collection of topic subscriptions.
```

--------------------------------

### Configure cURL CA Info in php.ini

Source: https://firebase-php.readthedocs.io/latest/troubleshooting.html

Set the absolute path to the CA bundle in the php.ini file to resolve cURL certificate errors.

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

--------------------------------

### Set or replace data

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Use set() to overwrite data at a specific reference path. This operation replaces all existing data at that location, including child nodes.

```php
$database->getReference('config/website')
    ->set([
        'name' => 'My Application',
        'emails' => [
            'support' => 'support@example.com',
            'sales' => 'sales@example.com',
        ],
        'website' => 'https://app.example.com',
    ]);

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

--------------------------------

### Write server values

Source: https://firebase-php.readthedocs.io/latest/realtime-database.html

Use server-side placeholders like Database::SERVER_TIMESTAMP to record values generated by the Firebase server.

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

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

--------------------------------

### Auth::createCustomToken

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Creates a custom token for a given user ID, optionally including additional claims.

```APIDOC
## Auth::createCustomToken

### Description
Creates a custom token that can be used to authenticate a user or device. The token expires after one hour.

### Parameters
- **uid** (string) - Required - The unique identifier for the user or device.
- **additionalClaims** (array) - Optional - Additional claims to be included in the custom token.

### Example
```php
$uid = 'some-uid';
$additionalClaims = ['premiumAccount' => true];
$customToken = $auth->createCustomToken($uid, $additionalClaims);
$customTokenString = $customToken->toString();
```
```

--------------------------------

### Publish Remote Config Template

Source: https://firebase-php.readthedocs.io/latest/remote-config.html

Publishes the provided template to Firebase. Handles RemoteConfigException for potential failures during the process.

```php
use Kreait\Firebase\Exception\RemoteConfigException

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

--------------------------------

### signInWithCustomToken

Source: https://firebase-php.readthedocs.io/latest/authentication.html

Signs in a user using a custom Firebase token.

```APIDOC
## $auth->signInWithCustomToken($customToken)

### Description
Authenticates a user using a custom token.

### Parameters
- **$customToken** (string) - Required - The custom token.
```
Tokens:
Raw