README

Use Google Firebase without the requirement of having the gRPC extension for php installed. This is ideal for shared hosting environments. This package is totally based on Firestore REST API

Authentication / Generate API Key

Visit Google Cloud Firestore API
Select your desired project.
Select Credentials from left menu and select API Key from Server key or Create your own credentials

Installation

You can install the package via composer:

composer require bensontrent/firestore-php

or install it by adding it to composer.json then run composer update

"require": {
    "bensontrent/firestore-php": "^3.0",
}

Dependencies

PHP 7.3 and above (PHP 8+ supported)

The bindings require the following extensions in order to work properly:

If you use Composer, these dependencies should be handled automatically. If you install manually, you'll want to make sure that these extensions are available.

Usage

Initialization

require 'vendor/autoload.php';

use MrShan0\PHPFirestore\FirestoreClient;

$firestoreClient = new FirestoreClient('my-project-id', 'MY-API-KEY-xxxxxxxxxxxxxxxxxxxxxxx', [
    'database' => '(default)',
]);

Note: You likely won't need to change the 'database' => '(default)' line.

Adding a document

Make sure your Firebase Rules allow you to write to the $collection you wish to modify or you will get an error: You do not have permission to access the requested resource

require 'vendor/autoload.php';

use MrShan0\PHPFirestore\FirestoreClient;

// Optional, depending on your usage
use MrShan0\PHPFirestore\Fields\FirestoreTimestamp;
use MrShan0\PHPFirestore\Fields\FirestoreArray;
use MrShan0\PHPFirestore\Fields\FirestoreBytes;
use MrShan0\PHPFirestore\Fields\FirestoreGeoPoint;
use MrShan0\PHPFirestore\Fields\FirestoreObject;
use MrShan0\PHPFirestore\Fields\FirestoreReference;
use MrShan0\PHPFirestore\Attributes\FirestoreDeleteAttribute;

$collection = 'myCollectionName';

$firestoreClient->addDocument($collection, [
    'myBooleanTrue' => true,
    'myBooleanFalse' => false,
    'null' => null,
    'myString' => 'abc123',
    'myInteger' => 123456,
    'arrayRaw' => [
        'string' => 'abc123',
    ],
    'bytes' => new FirestoreBytes('bytesdata'),
    'myArray' => new FirestoreArray([
        'firstName' => 'Jane',
    ]),
    'reference' => new FirestoreReference('/users/23'),
    'myObject' => new FirestoreObject(['nested1' => new FirestoreObject(
        ['nested2' => new FirestoreObject(
            ['nested3' => 'test'])
        ])
     ]),
    'timestamp' => new FirestoreTimestamp,
    'geopoint' => new FirestoreGeoPoint(1,1),
]);

NOTE: Pass third argument if you want your custom document id to set else auto-id will generate it for you. For example:

$firestoreClient->addDocument('customers', [
    'firstName' => 'Jeff',
], 'myOptionalUniqueID0123456789')

use MrShan0\PHPFirestore\FirestoreDocument;

$document = new FirestoreDocument;
$document->setObject('myNestedObject', new FirestoreObject(
    ['nested1' => new FirestoreObject(
        ['nested2' => new FirestoreObject(
            ['nested3' => 'test'])
            ])
        ]
    ));
$document->setBoolean('myBooleanTrue', true);
$document->setBoolean('myBooleanFalse', false);
$document->setNull('null', null);
$document->setString('myString', 'abc123');
$document->setInteger('myInteger', 123456);
$document->setArray('myArrayRaw', ['string'=>'abc123']);
$document->setBytes('bytes', new FirestoreBytes('bytesdata'));
$document->setArray('arrayObject', new FirestoreArray(['string' => 'abc123']));
$document->setTimestamp('timestamp', new FirestoreTimestamp);
$document->setGeoPoint('geopoint', new FirestoreGeoPoint(1.11,1.11));

$firestoreClient->addDocument($collection, $document, 'customDocumentId');

And..

$document->fillValues([
    'myString' => 'abc123',
    'myBoolean' => true,
    'firstName' => 'Jane',
]);

Special characters in the field name

If you want to use special characters in the field name, you have to use backticks.

$document->fillValues([
    '`teléfono`' => '1234567890',
    '`contraseña`' => 'secretPassword',
]);

You could use addNestedDocuments if you have multiple nested objects

require 'vendor/autoload.php';

use MrShan0\PHPFirestore\FirestoreClient;

$collection = 'myCollectionName';

$originalData = [
    'name' => 'My Application',
    'emails' => [
        'support' => 'support@example.com',
        'sales' => 'sales@example.com',
    ],
    'website' => 'https://app.example.com',
    'myObject' => [
        'nested1' => [
            'name' => 'My Application',
            'emails' => [
                'support' => 'support@example.com',
                'sales' => 'sales@example.com',
            ],
            'nested2' => [
                'name' => 'My Application',
                'emails' => [
                    'support' => 'support@example.com',
                    'sales' => 'sales@example.com',
                ],
                'nested3' => [
                    'name' => 'My Application',
                    'emails' => [
                        'support' => 'support@example.com',
                        'sales' => 'sales@example.com',
                    ]
                ]
            ]
        ]
    ]
];

$firestoreClient->addNestedDocuments($collection, $originalData);

This just formats the array before using the addDocument function

require 'vendor/autoload.php';

use MrShan0\PHPFirestore\FirestoreClient;
use MrShan0\PHPFirestore\Fields\FirestoreObject;

$collection = 'myCollectionName';

$originalData = [
    'name' => 'My Application',
    'emails' => new FirestoreObject( [
        'support' => 'support@example.com',
        'sales' => 'sales@example.com',
    ]),
    'website' => 'https://app.example.com',
    'myObject' => new FirestoreObject([
        'nested1' => new FirestoreObject([
            'name' => 'My Application',
            'emails' => new FirestoreObject([
                'support' => 'support@example.com',
                'sales' => 'sales@example.com',
            ]),
            'nested2' => new FirestoreObject([
                'name' => 'My Application',
                'emails' => new FirestoreObject([
                    'support' => 'support@example.com',
                    'sales' => 'sales@example.com',
                ]),
                'nested3' => new FirestoreObject([
                    'name' => 'My Application',
                    'emails' => new FirestoreObject( [
                        'support' => 'support@example.com',
                        'sales' => 'sales@example.com',
                    ])
                ])
            ])
        ])
    ])
];

Inserting/Updating a document

Update (Merge) or Insert document

Following will merge document (if exist) else insert the data.

use MrShan0\PHPFirestore\Attributes\FirestoreDeleteAttribute;

$firestoreClient->updateDocument($documentRoot, [
    'newFieldToAdd' => 'Jane Doe',
    'existingFieldToRemove' => new FirestoreDeleteAttribute
]);

NOTE: Passing 3rd argument as a boolean true will force check that document must exist and vice-versa in order to perform update operation.

For example: If you want to update document only if exist else MrShan0\PHPFirestore\Exceptions\Client\NotFound (Exception) will be thrown.

use MrShan0\PHPFirestore\Attributes\FirestoreDeleteAttribute;

$firestoreClient->updateDocument($documentPath, [
    'newFieldToAdd' => 'Jane Doe',
    'existingFieldToRemove' => new FirestoreDeleteAttribute
], true);

format for documentPath:

<collectionName>/<documentName>

Overwirte or Insert document

use MrShan0\PHPFirestore\Attributes\FirestoreDeleteAttribute;

$firestoreClient->setDocument($collection, $documentId, [
    'newFieldToAdd' => 'Jane Doe',
    'existingFieldToRemove' => new FirestoreDeleteAttribute
], [
    'exists' => true, // Indicate document must exist
]);

Deleting a document

$collection = 'collection/document/innerCollection';
$firestoreClient->deleteDocument($collection, $documentId);

List documents with pagination (or custom parameters)

$collections = $firestoreClient->listDocuments('users', [
    'pageSize' => 1,
    'pageToken' => 'nextpagetoken'
]);

Note: You can pass custom parameters as supported by firestore list document

Get field from document

$document->get('bytes')->parseValue(); // will return bytes decoded value.

// Catch field that doesn't exist in document
try {
    $document->get('allowed_notification');
} catch (\MrShan0\PHPFirestore\Exceptions\Client\FieldNotFound $e) {
    // Set default value
}

Firebase Authentication

Sign in with Email and Password.

$firestoreClient
    ->authenticator()
    ->signInEmailPassword('testuser@example.com', 'abc123');

Sign in Anonymously.

$firestoreClient
    ->authenticator()
    ->signInAnonymously();

Retrieve Auth Token

$authToken = $firestoreClient->authenticator()->getAuthToken();

TODO

Added delete attribute support.
Add Support for Object, Boolean, Null, String, Integer, Array, Timestamp, GeoPoint, Bytes
Add Exception Handling.
List all documents.
List all collections.
Filters and pagination support.
Structured Query support.
Transaction support.
Indexes support.
Entire collection delete support.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please use the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

bensontrent / firestore-php

Maintainers

Details