Firequent Laravel Package

Technical Evaluation

Architecture fit

• Firequent is a translation shim, not a relational engine: it maps Eloquent's model/query API onto Firestore's document/collection API. Fit is strong only for greenfield, GCP-native, document-shaped domains (user profiles, device/telemetry state, content feeds, notification records) where Firestore is already the system of record.
• Poor fit for anything depending on joins, whereHas, aggregates, reporting, ad-hoc admin queries, or cross-collection transactions. Eloquent's contract is only partially honored; several query shapes cannot be expressed in Firestore at all.
• Coupling is one-directional and deep: adopting this package means committing the bounded context to Firestore. It is not a swappable driver.
• Package targets the Laravel 6/7, PHP 7.x era (last release 2020-08-27). Any modern Laravel 10/11 codebase will likely require a fork or dependency-constraint surgery before the first line of product code.

Integration feasibility

• Initial lift is low: composer install, service-account/ADC credentials, a model extending the package base class, a collection name. A developer can ship single-collection CRUD in days.
• The real cost sits in the translation gap. Every query must be validated against Firestore's filter and composite-index rules, and composite indexes must be authored, versioned, and deployed alongside code (treat firestore.indexes.json as schema).
• No migrations, no foreign keys, no artisan migrate. Seeding, fixtures, and test-data tooling must be built or borrowed; CI should run against the Firestore emulator, not production.
• Dual-connection operation is feasible — Firestore does not occupy Laravel's default DB connection — which makes a strangler approach viable.

Technical risk

• Abandonment (high): 26 stars, single maintainer, no release in ~5 years. Assume you own the code; budget for vendoring/forking.
• Semantic drift (high): unsupported operators may be approximated or silently mis-served, producing wrong results in product surfaces rather than loud errors.
• Cost risk (high): Firestore bills per document read/write. Idiomatic Eloquent patterns (with(), loops, count(), N+1) multiply both latency and spend. A convenience ORM can become an expensive database.
• Security posture: the package runs with service-account privileges, so Firestore security rules do not protect server-side paths — all authorization must be enforced in the application layer.
• Observability gap: Telescope, query logs, and APM query panels will not meaningfully capture Firestore operations; custom instrumentation is required.
• Lock-in: reverting to SQL is a data-layer rewrite, not a configuration change.

Key questions

1. Is Firestore already the system of record, or is this package being used to avoid operating a database?
2. Which product surfaces genuinely need document semantics (offline sync, realtime listeners, multi-region) versus merely "we're on GCP"?
3. What are the acceptable p95 latency and per-request document-read budget?
4. Will we commit an owner to maintain a fork against our Laravel/PHP versions?
5. Do we need multi-entity transactional consistency? Firestore transactions are bounded and document-level.

Integration Approach

Stack fit

• Natural fit inside the Firevel / Laravel-on-Cloud-Run reference architecture, or any PHP 7.4–8.0 service on GCP using Application Default Credentials.
• Dependency conflict risk with apps already pinning newer google/cloud-* packages (Pub/Sub, Secret Manager share the same monorepo release train).
• Practically incompatible with packages that assume SQL semantics: Scout drivers, relational permission packages, Nova/Backpack resource queries, debugbar query panels, and most BI/reporting layers.

Migration path

• Do not lift-and-shift a relational domain. Use a strangler pattern: pick one bounded context (e.g., notification state, device registry) and hide Firestore behind a repository interface so product code never depends on Eloquent directly.
• For genuine data migration: export → remodel into denormalized documents (embedding vs. subcollection is the dominant decision) → dual-write window → cut reads → decommission. Modeling effort will exceed coding effort by a wide margin.
• Keep the relational store authoritative until the pilot proves cost and latency SLOs.

Compatibility

• Pin and test the Laravel/PHP matrix explicitly; if the target is Laravel 10+, scope a fork that bumps PHP and Google SDK constraints.
• Run CI against the Firestore emulator. Version composite indexes in the repo. Add guardrails that throw on unsupported query shapes rather than degrading silently.

Sequencing

1. Weeks 1–2 — Spike: CRUD plus one representative multi-filter query; measure document reads per request and p95 latency; prove emulator-based CI.
2. Weeks 3–4 — Harden: fork/vendor and modernize if needed; add query-shape validation, structured logging, and read-count instrumentation.
3. Weeks 5–8 — Pilot: one bounded context behind a repository interface; load test at projected QPS; stand up a cost dashboard.
4. Decision gate: if the pilot breaches read budget or latency targets, either drop the Eloquent abstraction for the raw Firestore SDK or return to SQL.

Operational Impact

Maintenance

• Assume full ownership: no vendor SLA, no security-patch stream, no roadmap. Budget roughly 10–20% of one engineer ongoing for Laravel and Google SDK bumps, emulator updates, and translation fixes.
• Index management becomes a production change process. A missing composite index is a runtime exception that often appears only under a rarely used filter combination.

Support

• Community support is effectively nil at 26 stars; escalation means reading Firestore docs and package source. Expect long mean-time-to-resolution on novel failures.
• Skill gap is the quiet hazard: engineers fluent in Eloquent will write SQL-shaped code Firestore cannot serve. Add lint/review rules and Firestore-specific design training.

Scaling

• Firestore itself scales well; the ORM layer becomes the bottleneck through per-document round trips and serialization overhead.
• List endpoints degrade linearly with result size. Avoid offset pagination (skipped documents are billed); require cursor pagination on indexed fields.
• Cost scales with query patterns rather than data volume — this is a product-visible metric, so instrument document reads per endpoint and set budgets early.

Failure modes

• Missing composite index → query exception, often first seen in production on an edge-case filter.
• Unsupported operator silently approximated → incorrect UI data rather than an error.
• Quota exhaustion / 429 bursts → partial page renders if error handling is naive.
• ADC/credential misconfiguration in a new environment → total data-layer outage with no schema check to catch it at boot.
• Large result sets buffered into PHP memory → fatal memory errors, since there is no server-side cursor equivalent to PDO.
• Dual-write drift against the relational store without reconciliation jobs.

Ramp-up

• 1–2 days for a Laravel developer to ship basic CRUD; 2–3 weeks to internalize Firestore's query, index, and pricing model well enough to design documents correctly.
• The ORM hides exactly the wrong things — it makes Firestore look relational, which is the core onboarding hazard. Mandate a document-modeling design review before any production code.

TPM recommendation: treat Firequent as a narrow enabler for a specific GCP-native bounded context, gated by a timeboxed spike and an explicit fork-maintenance commitment. Do not adopt it as the default persistence layer for an existing relational Laravel application; the 0.38 opportunity score is consistent with "worth a spike, not a platform bet."