README

这是一个小型的包，用于在 Symfony 应用程序中持久化和管理与 Google Cloud Firestore 数据库关联的实体。

要求

此包需要 PHP 8.2+ 和 Symfony 7+。

此包还严重依赖于 Google Cloud Firestore PHP 客户端，其技术要求相同（最值得注意的是 PHP gRPC 和 Protobuf 扩展）。有关更多详细信息，请参阅 Google 的文档。

安装

如果您有 Symfony Flex，则有一个 contrib recipe 可用

composer require tiriel/firestore-odm-bundle

这样就完成了，您现在可以开始了。

如果您尚未安装 Flex，请先像上面那样要求包。然后，在 config/bundles.php 文件中启用包

<?php

return [
    // ...
    Tiriel\FirestoreOdmBundle\TirielFirestoreOdmBundle::class => ['all' => true],
];

现在您可以创建一个包含以下内容的 config/packages/tiriel.yaml

tiriel_firestore_odm:
    # Replace the following values by your own
    project_name: my-project
    # Can be an env var, a string to a file, or a yaml array with the values from the credentials file
    service_account: '%kernel.project_dir%/config/secrets/my_project.json'

用法

DTO 或实体

您的应用程序中的每个 DTO 类都会在 Firestore 数据库中根据其 FQCN 创建一个新的集合。

您可以使用任何 DTO 作为实体。唯一的要求是它们实现 Tiriel\FirestoreOdmBundle\Dto\Interface\PersistableDtoInterface 作为标记，并确保存在 getId() 方法。此 id 可以是字符串、整数或 Symfony Uuid。

示例

use Symfony\Component\Uid\Uuid;
use Tiriel\FirestoreOdmBundle\Dto\Interface\PersistableDtoInterface;

class Image implements PersistableDtoInterface
{
    private ?Uuid $id = null;

    private ?string $path = null;
    
    //...
    
    public function getId(): Uuid|string
    {
        return $this->id;
    }

    // ...

现在您可以为您创建一个 DTO 管理器。

DTO 管理器

为了对 Firestore DTO 执行查询，您需要创建一个扩展 Tiriel\FirestoreOdmBundle\Manager\FirestoreDtoManager 的管理器。在内部，通过指定此管理器附加的 DTO 来覆盖 FirestoreDtoManager::DTO_CLASS 常量的值

use App\Dto\Image;
use Tiriel\FirestoreOdmBundle\Manager\FirestoreDtoManager;

class ImageFirestoreDtoManager extends FirestoreDtoManager
{
    public const DTO_CLASS = Image::class;
}

这样您就完成了，您现在可以使用新的 DTO 和其管理器。

内部，此包为您创建了一个别名以自动注入为 DtoManagerInterface $dtoNameManager。

使用我们的 ImageFirestoreDtoManager 的示例

use Tiriel\FirestoreOdmBundle\Manager\Interface\DtoManagerInterface;

class ImageController extends AbstractController
{
    #[Route('/images', name: 'app_image_index', methods: ['GET'])]
    public function index(DtoManagerInterface $imageManager): Response
    {
        // ...

可用方法

所有管理器都提供了相同的接口和方法

interface DtoManagerInterface
{
    /**
     * Returns a single DTO matching the given $id 
     * 
     * @throws EntryNotFoundFirestoreException is the given id is not found
     */
    public function get(string $id): ?PersistableDtoInterface;

    /**
     * @return iterable the DTOs matching the given criteria
     * @param array $criteria 
     * Can be a single array matching Google SDK's `where` method, 
     * or an array of arrays:
     * 
     * $criteria = ['name', '=', 'foo']
     * or 
     * $criteria = [
     *      ['name', '=', 'foo'],
     *      ['createdAt', '>=', '01-01-1970'],
     *  ]
     */
    public function search(array $criteria): iterable;

    /**
     * @return iterable the full list of documents from the collection
     */
    public function getList(): iterable;

    /**
     * Persists a new entry in Firestore and generates a new id 
     * (Uuid v7 as of now)
     * 
     * @throws NonUniqueEntryFirestoreException if the generated Uuid is not unique
     */
    public function create(PersistableDtoInterface $dto): void;

    /**
     * @param PersistableDtoInterface $dto to be updated in the collection
     * @throws EntryNotFoundFirestoreException if the DTO's id doesn't exist in the collection
     */
    public function update(PersistableDtoInterface $dto): void;

    /**
     * @param PersistableDtoInterface $dto to be removed from the collection
     * @throws EntryNotFoundFirestoreException if the DTO's id doesn't exist in the collection
     */
    public function remove(PersistableDtoInterface $dto): void;

    /**
     * @return int the full count of documents in the collection
     */
    public function count(): int;

    /**
     * @return string the classname of the DTO associated to this manager
     */
    public function getClass(): string;
}

所有管理器还包括一个来自 Google\Cloud\Firestore\CollectionReference 的 protected CollectionReference $collection 对象。您可以使用它来创建自己的自定义查询或分页。

与 Symfony Security 的用法

如果您想使用 Firestore 存储安全流程的用户，您可以检查我的其他包： Firestore-Security-Bridge。

此包定义了类和用户提供者，以帮助您将 Firestore 作为用户源使用。