Neo4J Common Laravel Package

Product Decisions This Supports

• Graph-database adoption as an architectural bet. This library is the shared plumbing beneath the GraphAware Neo4j PHP client (Cypher query building, result formatting, response mapping, auth helpers). Adopting it is only meaningful if the product has already decided Neo4j — or Bolt-compatible graph stores — belongs in the stack. It is a consequence of that roadmap decision, not a driver of it.
• Feature scoping for relationship-heavy capabilities. Use cases that justify the surrounding graph stack, and by extension this dependency, include: recommendation and "people you may know" surfaces, fraud-ring and identity-linkage detection, permission/entitlement graphs, knowledge-graph search, supply-chain or dependency tracing, and multi-hop hierarchy traversal where SQL joins become unreadable.
• Build vs. buy on the data-access layer. The real decision is not "this package vs. nothing" but "thin internal Cypher/HTTP wrapper vs. community client vs. vendor-supported driver." This package sits inside the community-client option, which is the lowest-effort path if the team is small and the graph model is still being validated.
• Roadmap gating through a spike. Because the package has 24 stars, zero dependents, and an unasserted license (NOASSERTION), it should appear in the roadmap as a time-boxed technical spike with a go/no-go gate — not as a committed line item in a delivery plan.
• Platform-neutral PHP fit. It is framework-agnostic PHP, not Laravel-native; it is usable from Laravel but brings no service provider, config, Eloquent-style integration, or facade. That keeps it portable across Laravel, Symfony, and plain PHP services — useful if the graph work may be extracted into a separate service later.

When to Consider This Package

Consider it when all of the following hold:

• Neo4j is already chosen and engineering is using, or intends to use, graphaware/neo4j-php-client — in which case this arrives as a transitive dependency and the practical task is risk acceptance, not selection.
• The work is internal, non-customer-facing, or early-stage (prototypes, internal tooling, data exploration), where a stalled upstream is a maintainability annoyance rather than an outage.
• You need Cypher construction and result-mapping helpers rather than a full ORM, and the team is comfortable owning a thin wrapper.
• You can pin an exact version, vendor the source, and monitor upstream — and legal has cleared or explicitly accepted the NOASSERTION license classification.

Look elsewhere when:

• Neo4j is not a settled decision — the choice of driver should follow the data model, not precede it.
• The dependency would sit on a customer-facing critical path requiring SLAs, security patching, or a support contract.
• License certainty is mandatory (enterprise distribution, acquisition diligence, open-source policy gates): NOASSERTION is not a cleared license.
• You need active maintenance and documentation; low stars, zero dependents, and a small maintainer base signal abandonment risk.
• A Laravel-native integration is required — prefer a maintained Laravel graph package or the official Neo4j PHP driver with a repository abstraction of your own.
• The need is simple enough that a thin internal HTTP/Bolt client over raw Cypher is cheaper than carrying an unmaintained layer.

How to Pitch It (Stakeholders)

To executives: This is a small utility library that lets our PHP services talk to a graph database. It unlocks features that are awkward in SQL — recommendations, fraud linkage, permission graphs — and it costs us almost nothing to try. The caveat is risk, not price: it has a very small community, no downstream users we can point to, and an unclear license. My recommendation is a short, time-boxed evaluation rather than a production commitment, with legal reviewing the license in parallel. If both come back clean, it saves us weeks of building our own database plumbing; if not, we walk away with a validated data model and no sunk cost.

To engineering: Treat this as infrastructure, not a feature dependency. It is framework-agnostic — no Laravel service provider, no config — so wire it behind our own repository interface so the driver can be swapped for the official client or a raw Bolt/HTTP adapter without touching domain code. Pin exact versions, vendor the source, and add a single integration test that exercises the query/result-mapping path we actually depend on, so an upstream stall is visible rather than silent.

The ask: a two-week spike, a license review, and a documented fallback path — approved as an experiment, not as an architecture decision.