Fluentaql Laravel Package

Technical Evaluation

What the package actually is. FluentAQL is a standalone PHP query builder that constructs ArangoDB AQL strings (plus bind variables) through a fluent, Laravel-Query-Builder-style API. It is not a driver, not an ORM, and not a connection manager — it terminates at "produce a query object," which is the single most important architectural fact in this assessment. It has no runtime coupling to Laravel's container, HTTP kernel, or Eloquent, so it can be adopted or removed as a leaf dependency rather than something that reshapes application structure.

Architecture fit. Fit is conditional and narrow: this package is only relevant if ArangoDB is already a committed part of the persistence strategy. In a MySQL/Postgres + Eloquent estate it is dead weight, and ArangoDB's multi-model (document + graph + key-value) semantics mean it is not a drop-in for existing relational access patterns. Where ArangoDB is in play, FluentAQL is best treated as an internal component of the laravel-arangodb ecosystem from the same maintainer rather than something application code calls directly — the driver should own the builder.

Integration feasibility. Mechanically trivial: MIT license, Composer-installable, small public surface. The blockers are not mechanical. The repository is archived, last release 2022-05-16, 12 stars, zero dependents, and an internal health score of 0.26. That combination means: no upstream triage, no PHP/Laravel version-compatibility work since 2022, no CVE response path, and no ecosystem evidence that the query shapes we would generate have ever been exercised in production by anyone else. Feasibility therefore reduces to "can we own it," not "can we install it."

Technical risk. Ranked:

1. Semantic drift from the server. The package encodes AQL grammar and query-shape knowledge. ArangoDB has continued to evolve (ArangoSearch/SEARCH, new traversal and OPTIONS semantics, deprecations). An archived builder will silently fail to express newer constructs and may emit deprecated ones. The failure mode is a parse error at runtime, or worse, a syntactically valid query with different semantics.
2. Correctness of binding behavior. A query builder's highest-severity defect class is mishandling parameter binding versus string interpolation — either an AQL injection vector or a silent escaping bug that returns wrong results. With no maintainer and no visible test matrix, we must verify this ourselves before trusting it with user-influenced input.
3. Abandoned-dependency exposure. Pinned older PHP constraints will eventually block platform upgrades; SCA tooling will flag the package as unmaintained; and a dormant Packagist namespace is a low-probability but non-zero supply-chain concern.
4. Coverage gaps. Unverified: nested graph traversals, SEARCH/ArangoSearch, joins across collections, LET/subquery composition, OPTIONS blocks, and query-explain integration.

Key questions for the maintainer/team.

• Is ArangoDB a strategic, funded part of the platform, or an experiment? (If experiment, this whole evaluation is moot.)
• Will we consume FluentAQL directly, or only transitively via laravel-arangodb? If the latter, is that package also archived, and does it pin FluentAQL?
• What are the declared php and illuminate/* constraints, and does the package install cleanly on our current PHP runtime without --ignore-platform-reqs?
• Does it use parameterized bind variables for all literal values, and are collection/attribute names validated?
• What is the test suite's AQL-version coverage, and does it run against a live ArangoDB in CI?
• Which of our planned query shapes are not expressible — and can we express them via raw AQL escape hatches?

Integration Approach

Stack fit. Treat this as conditionally compatible, not broadly compatible. Decision gate: does the target service already run ArangoDB and already depend on laravel-arangodb? If yes, FluentAQL is a natural low-level piece and the work is diligence plus containment. If no, do not introduce ArangoDB because of this package — the builder is the cheapest part of that decision and the least of its risks.

Migration path. Three viable paths, in preference order:

1. Containment behind an internal abstraction (recommended). Define a thin internal query-interface (e.g., QueryBuilderFactory / AqlCompiler ports) and bind FluentAQL as one adapter. Application code never imports the vendor namespace. This makes a future fork, replacement, or removal a one-file change and is the single highest-leverage mitigation available given the package's health signals.
2. Vendor-fork. Fork into an internal namespace/Composer repository, add PHP-version and ArangoDB-version CI, and own the changelog. Justified only if the fluent API is materially valuable and our query surface is broad; the codebase is likely small enough that "fork" is closer to "adopt a file tree."
3. Replace with a hand-rolled builder over the official arangodb-php driver or the HTTP API. Cheapest to reason about, highest upfront cost, best long-term posture for a small, stable set of query shapes.

Avoid the fourth path — consuming the archived package directly in application code with an unpinned constraint — entirely.

Compatibility. Verify rather than assume: composer.json PHP constraint, illuminate/support (or absence thereof), PSR-4 autoload correctness, and behavior under our exact PHP minor version with E_ALL deprecation reporting on. Lock the version explicitly in composer.json, commit the lockfile, and add the package to the SCA/abandoned-package allowlist with a documented owner and review date so auditors and future engineers see a decision rather than an oversight.

Sequencing.

1. Two-day spike against a real ArangoDB instance: install, build our top 10–15 intended query shapes, diff emitted AQL against hand-written AQL, confirm bind-variable usage.
2. Gap log: which shapes require raw-AQL fallback, which are unsupported.
3. Architecture decision record capturing fork-versus-replace and naming an internal owner.
4. Wire the internal abstraction before any production code depends on the library.
5. CI hardening: static analysis, the spike's query corpus as regression tests, and an ArangoDB container in CI.
6. Only then integrate into the service.

Operational Impact

Maintenance. We become the de facto maintainer regardless of which path we pick — the question is only whether we pay that cost in a fork or in an adapter. The package is small, so the absolute effort is modest, but it is permanent and it lands on whoever owns persistence. Budget explicitly for: PHP runtime upgrades, ArangoDB server upgrades (each one is a compatibility review of the emitted AQL), and dependency-bot noise from an unmaintained package.

Support. There is no upstream support tier, no issue triage, no security advisory channel. Any defect — including a wrong-results defect — is ours to diagnose. Because failures surface as AQL parse errors from the database rather than as PHP exceptions with clean stack traces, on-call engineers will need a documented triage path from "500 from ArangoDB" back to "query built by the builder." Put that runbook in place during integration, not after the first incident.

Scaling. Effectively free at runtime: the builder is string composition on the request path with no I/O, no connection pooling, no caching layer to reason about. It scales with the PHP process like any pure computation. The scaling risk is entirely organizational — the number of engineers who understand both AQL and the builder's quirks — not technical. Horizontal scale-out of the service raises no concerns here; query performance is a function of our AQL and ArangoDB indexing, and the builder neither helps nor hinders that.

Failure modes to instrument for.

• Malformed AQL from unsupported constructs → runtime parse errors under specific input combinations only (highest-likelihood production surprise).
• Binding/escaping defects → incorrect results rather than exceptions; mitigate with golden-query regression tests, not monitoring.
• PHP deprecation/notice noise from a 2022-era codebase → log spam and alert fatigue; suppress narrowly rather than globally.
• Platform upgrade blockage → the package's PHP constraint becomes the constraint for the whole service; track this as a known future blocker with a dated review.
• Compliance/SCA flagging → abandoned dependency surfacing in security review; pre-empt with the allowlist entry and ADR.

Ramp-up. The API is fluent and deliberately Laravel-shaped, so a mid-level Laravel developer is productive in hours for simple filters, sorts, and projections. The real ramp is AQL itself — graph traversals, SEARCH, multi-collection joins — which is a multi-week competency independent of this package and which the package's likely-thin documentation will not teach. Assume engineers will read the source. Plan for one engineer to become the designated owner of both AQL and the builder adapter before the service goes live; a team with zero AQL depth and an archived builder is a bad combination.

Bottom line. Do not adopt as a greenfield dependency. If ArangoDB is already strategic, adopt it only behind an internal abstraction, with a named owner, a pinned version, a query-regression corpus, and a documented fork-or-replace decision — the low health score and archived status are not disqualifying for a small, leaf-level library, but they shift the full lifecycle cost onto us, and that cost should be accepted deliberately rather than discovered during a PHP upgrade.