Neo4J Common Laravel Package

Technical Evaluation

What the package actually is

• A low-level utility library (HTTP transport, request/response plumbing, shared interfaces) extracted from the GraphAware Neo4j PHP ecosystem. It is a building block for graphaware/neo4j-php-client and the OGM, not a standalone Neo4j driver.
• There is no Laravel-facing surface: no service provider, no config file, no facade, no Eloquent integration. composer require alone delivers zero product capability.

Architecture fit

• Poor as a direct dependency. It would only enter the codebase as a transitive dependency beneath a Neo4j client. Value is realized entirely through the client you choose, so the architectural decision is "which Neo4j client," not "should we use neo4j-common."
• Its abstraction layer is HTTP/REST-oriented, which predates and does not cover Bolt — the protocol modern Neo4j deployments expect. Any architecture that routes around it is likely better positioned.

Integration feasibility

• Trivially installable, non-trivially useful. The real integration work is: choosing an actively maintained Bolt-capable client (e.g., the Laudis fork lineage), defining a repository/service boundary, and handling result mapping.
• If a chosen client pulls this in transitively, the work is version pinning and a dependency audit — not feature integration.

Technical risk

• Maintenance risk — high. 24 stars, 0 dependents, no recent activity signal, single-org ownership. Effectively bus factor 1 and frozen. If it breaks, we own it.
• License risk — blocking until resolved. NOASSERTION means GitHub could not classify it. GraphAware projects are typically permissive, but we cannot ship on an assumption; legal review is required before any production dependency.
• Runtime compatibility risk — high. Libraries of this vintage typically pin older PHP and Guzzle majors. Laravel 10/11 ship guzzlehttp/guzzle 7 on PHP 8.1+; a Guzzle 5/6-era constraint will produce Composer conflicts or force an isolated, out-of-date install.
• Protocol drift risk — medium/high. REST endpoints and response shapes have changed across Neo4j 3.x → 4.x → 5.x. An unmaintained transport layer is the most likely place to break silently after a database upgrade.

Key questions for the team

1. Is a graph database genuinely required, or is this a "relationships are awkward in SQL" problem solvable with Postgres recursive CTEs or a materialized adjacency model?
2. Which client actually consumes this package in our target install, and what is its maintenance status and PHP 8.x support?
3. Has legal cleared the NOASSERTION license? What is the redistribution/attribution obligation?
4. Who owns Neo4j operations (backup, cluster, upgrade cadence) if we adopt this path?
5. If this library breaks, do we have the appetite to vendor a fork?

Integration Approach

Stack fit

• Weak. The package sits below the level at which Laravel offers leverage — no container bindings, no queue/event hooks, no testing helpers. Everything must be hand-wired and hand-mocked.
• Recommended shape if the graph use case survives scrutiny: define an application-owned interface (GraphRepository / RelationshipQueryService), implement it with a maintained Bolt client, and keep the vendor library entirely behind that boundary. This preserves optionality and makes the eventual client swap a one-file change.

Migration path

• Do not adopt this package deliberately. Instead:
  1. Validate the graph use case and the specific query patterns it must serve.
  2. Spike a Bolt-based, PHP 8.x-compatible client in a throwaway branch against a local Neo4j container.
  3. Run a full composer why graphaware/neo4j-common audit — accept it only if it arrives transitively and is pinned.
  4. If it is a transitive dependency, vendor/fork it under our namespace so we control patches.
• If the spike shows the graph need is marginal, the correct migration is away — stay on the relational store.

Compatibility considerations

• Verify PHP constraint against our Laravel PHP floor (8.1/8.2/8.3) — expect it to fail.
• Verify Guzzle major alignment with Laravel's own guzzlehttp/guzzle 7 requirement; a conflict here is the single most likely hard blocker.
• Verify PSR-7/PSR-18 conformance so the transport can be swapped or mocked in tests.
• Confirm Neo4j server version support explicitly — do not infer it from the README.

Sequencing

1. Product/architecture: confirm graph requirement and success metrics (week 1).
2. Legal: license determination (parallel, week 1–2 — this gates everything).
3. Engineering: client + transport spike against a pinned Neo4j version (week 2–3).
4. Engineering: wrap behind an application interface, build contract tests (week 3–4).
5. Decision gate: proceed only if license clears, the client is maintained, and Composer resolves cleanly on our PHP/Guzzle versions.

Recommendation: Reject as a direct dependency. Treat as an acceptable-only-transitive artifact, and treat the license and PHP/Guzzle compatibility checks as hard go/no-go gates.

Operational Impact

Maintenance

• Effectively frozen upstream. We absorb all maintenance: PHP deprecation fixes, Guzzle security patches, transport bug fixes. Budget an ongoing "unplanned upgrade tax" rather than a steady-state zero.
• Fork-and-vendor is the realistic long-term posture if it stays in the dependency tree; that means owning a private package and its release process.

Support

• No vendor, no SLA, no commercial backing, and a 24-star community that will not answer questions. The escalation path is "read the source" — acceptable for a small utility, unacceptable for anything on a critical path.
• Onboarding cost is asymmetric: trivial to understand, expensive to own.

Scaling

• HTTP/REST transport adds per-query round-trip and serialization overhead versus Bolt, and offers weaker connection pooling, transaction management, and streaming semantics. Throughput ceilings will be hit earlier and diagnosed later.
• Horizontal scale is a function of Neo4j cluster operations and our ops maturity; this library neither helps nor is designed to.
• Under Laravel's async model (queues, Octane), a synchronous, unmaintained transport with unknown connection reuse behavior is a scaling and correctness concern.

Failure modes to design around

• Silent or misclassified transport failures — HTTP 4xx/5xx mapped loosely; no structured retry/timeout policy.
• Neo4j server upgrade breaking REST endpoint or response-shape expectations with no upstream fix forthcoming.
• PHP major-version upgrade producing fatals (dynamic property deprecation, typed curl handles) with no patch available.
• Composer conflict on Guzzle blocking a Laravel upgrade, forcing a fork on a Friday.
• License ambiguity surfacing late in a release or M&A review, blocking shipment.

Ramp-up

• Learning the API: hours — the surface is small.
• Owning it safely: ~1 sprint for the spike, license review, and interface wrapper, plus a recurring maintenance allocation each PHP/Laravel/Guzzle/Neo4j upgrade cycle.
• Team capability needed: at least one engineer comfortable reading and patching third-party PHP internals, plus database ops coverage for Neo4j itself.

Bottom line for the roadmap: low score (0.46) and low opportunity signal are consistent with the assessment. The package is a dormant internal detail of a dormant ecosystem. It should not appear as a named deliverable in any plan; the only thing worth funding is a time-boxed spike that determines whether Neo4j — and therefore any of this ecosystem — belongs in the stack at all.