README

无需安装 PHP 的 gRPC 扩展即可使用 Google Firebase。这是共享主机环境中的理想选择。本包完全基于 Firestore REST API

身份验证/生成 API 密钥

访问 Google Cloud Firestore API
选择您想要的工程。
从左侧菜单选择 凭据，然后从服务器密钥选择 API 密钥 或 创建自己的凭据

安装

您可以通过 composer 安装此包

composer require bensontrent/firestore-php

或将其添加到 composer.json，然后运行 composer update

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

依赖

PHP 7.3 及以上（支持 PHP 8+）

这些绑定需要以下扩展才能正常工作

如果您使用 Composer，这些依赖项应自动处理。如果您手动安装，请确保这些扩展可用。

使用

初始化

require 'vendor/autoload.php';

use MrShan0\PHPFirestore\FirestoreClient;

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

注意：您很可能不需要更改 'database' => '(default)' 行。

添加文档

请确保您的 Firebase 规则允许您写入要修改的 $collection，否则您将收到错误：您没有访问请求资源的权限

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

注意：如果您想设置自定义 文档 ID，请传递第三个参数，否则自动 ID 将为您生成。例如

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

和...

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

字段名称中的特殊字符

如果您想在字段名称中使用特殊字符，您必须使用反引号。

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

如果您有多个嵌套对象，可以使用 addNestedDocuments

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

这只是在使用 addDocument 函数之前格式化数组

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

插入/更新文档

更新（合并）或插入文档

以下操作将合并文档（如果存在）否则插入数据。

use MrShan0\PHPFirestore\Attributes\FirestoreDeleteAttribute;

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

注意：将第三个参数作为布尔值 true 传递将强制检查文档必须存在，反之亦然，以执行更新操作。

例如：如果您只想在文档存在时更新文档，否则将抛出 MrShan0\PHPFirestore\Exceptions\Client\NotFound（异常）。

use MrShan0\PHPFirestore\Attributes\FirestoreDeleteAttribute;

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

documentPath 的格式

<collectionName>/<documentName>

覆盖或插入文档

use MrShan0\PHPFirestore\Attributes\FirestoreDeleteAttribute;

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

删除文档

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

分页（或自定义参数）列出文档

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

注意：您可以传递由 firestore 列出文档支持的自定义参数

从文档中获取字段

$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 身份验证

使用电子邮件和密码登录。

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

匿名登录。

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

检索身份验证令牌

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

待办事项

添加删除属性支持。
添加对 Object、Boolean、Null、String、Integer、Array、Timestamp、GeoPoint、Bytes 的支持
添加异常处理。
列出所有文档。
列出所有集合。
过滤和分页支持。
结构化查询支持。
事务支持。
索引支持。
支持整个集合删除。

测试

composer test

变更日志

请参阅变更日志以获取更多关于最近更改的信息。

贡献

请参阅贡献指南以获取详细信息。

安全

如果您发现任何安全相关的问题，请使用问题跟踪器。

鸣谢

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

bensontrent / firestore-php

维护者

详细信息