Skip to content

Rewrite for PHP 8.3, add Firestore support - #7

Merged
adrorocker merged 13 commits into
masterfrom
1.0
Aug 24, 2026
Merged

Rewrite for PHP 8.3, add Firestore support#7
adrorocker merged 13 commits into
masterfrom
1.0

Conversation

@adrorocker

Copy link
Copy Markdown
Owner

Version 0.4 has not been installable for years. It required PHP 5.6 and Guzzle 6,
authenticated with a database secret in the query string, and called
GuzzleHttp\Psr7\stream_for(), which was removed in guzzle/psr7 2.0. A fresh
composer require could not boot. One repository also passed verify => false,
disabling TLS certificate verification.

This rewrites it for PHP 8.3+ and keeps the part that was worth keeping.

What changed

The bundled HTTP client is gone. It was never the valuable part, and
kreait/firebase-php does transport and credentials properly. What stays is the
entity and repository layer, rebuilt on top of a small Connection port.

Two adapters ship:

  • Realtime Database, through kreait/firebase-php
  • Firestore, over its REST API - no ext-grpc, so it runs on shared hosting

The entity layer knows nothing about Firebase, so the same entities,
repositories and queries run against either.

Notable

  • Records map to typed objects: backed enums, dates, nested entities and plain
    value objects. Reading goes through cuyz/valinor; writing does not, because
    private properties and nulls have to stay out of the payload.
  • Optimistic transactions with modify() and transaction(). Verified with real
    parallel processes rather than a mock: 4 writers, 20 increments, no lost
    updates on either backend.
  • Batched writes - a multi-path update on RTDB, a batched commit on Firestore.
  • Sentinel::ServerTimestamp and Sentinel::Remove.
  • Queries the Realtime Database cannot run throw UnsupportedQuery instead of
    quietly answering a different question.

Breaking

Everything. PhpFirebase\Firebase, the Guzzle client and the extra/ autoload
path are removed, namespaces moved, and repositories now take a Connection.
See UPGRADING.md.

Realtime Database users need to require kreait/firebase-php explicitly - it is
not a hard dependency, since Firestore users do not need it.

Not included

Streaming. RTDB can push changes over text/event-stream and PHP can consume
them given a long-running runtime, but holding a connection open and reconnecting
it is infrastructure. This package maps entities.

Checks

165 tests, PHPStan level 8, php-cs-fixer. CI runs on 8.3, 8.4 and 8.5.

Filtering and ordering are one field only here, so anything else throws
instead of quietly answering a different question.
google/cloud-firestore needs ext-grpc, which a library can't ask for.
Plain HTTP works fine and runs anywhere.
Resolution has to happen on the way to the wire, and I kept forgetting it
on new write paths, so it's a type you can't build without resolving.
@adrorocker
adrorocker merged commit 137dbe8 into master Aug 24, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant