Neo4J Laravel Eloquent Laravel Package

Product Decisions This Supports

• Feature decisions — graph-native capabilities. This package is the enabler for features that are awkward or slow on relational joins: multi-hop traversal (variable-depth), shortest-path, "people you may know," circular-dependency detection, entitlement/permission inheritance, and entity-resolution or knowledge-graph views. If those appear in your roadmap, this is a credible way to ship them without leaving Laravel.
• Build vs. buy (vs. bolt-on). The real decision is not "this package or nothing" — it is three options: (a) raw neo4j/neo4j-php-client plus a hand-rolled repository layer, (b) this package's Eloquent-style abstraction, (c) a separate graph service in another language. Choosing (b) trades a small amount of control for faster iteration and familiar model/relationship ergonomics; it is the lowest-effort path to a prototype.
• Architecture/roadmap decision — polyglot persistence. Adopting this commits you to running Neo4j alongside your relational store, with dual-write or sync concerns, a second backup/ops surface, and a data-consistency story the team must own. That is a real roadmap cost, not a library choice.
• Scoping and spike decisions. At 10 stars and a single recent release (Sep 2024), treat this as a spike enabler, not a platform commitment. It is cheap to validate in a timeboxed prototype whether graph queries actually beat your existing SQL for the specific feature — a decision-grade experiment for a fraction of the cost of a custom layer.
• Use cases where it pays off fastest: recommendation/similarity features, fraud-ring or abuse detection, org/space/folder permission trees, dependency and impact analysis, tag/topic graphs, and product catalog relationships.

When to Consider This Package

Consider it when all of the following hold:

• You are committed to Laravel/PHP and want graph capability without adding a second application stack or language.
• The feature is genuinely traversal-shaped — the value comes from 2+ hop queries, variable depth, or path search that your SQL is faking with recursive CTEs and multiple round-trips.
• You can treat Neo4j as a secondary, derived store (source of truth stays relational), which sidesteps most dual-write and transactionality risk.
• You accept the maintenance profile: small community, low star count, likely single-maintainer bus factor. You must be willing to vendor/fork it or wrap it behind your own interface so it is replaceable in days, not months.
• You have validated that MIT licensing and self-hosting Neo4j (Community vs. Enterprise features such as clustering, RBAC, hot backups) fit your compliance and ops model.

Look elsewhere — or don't do this — when:

• Transactions must span both stores atomically. Eloquent's transaction semantics do not extend across Neo4j; if your feature cannot tolerate eventual consistency, the abstraction will mislead the team.
• The need is a simple lookup or one-hop filter. Postgres recursive CTEs, a join table, or a materialized view will be cheaper to build, cheaper to run, and cheaper to hire for.
• You need a mature, well-supported ecosystem. A 10-star package with a single 2024 release is not a foundation for a multi-year, business-critical surface. Go direct to the official Neo4j PHP driver and own ~a few hundred lines of repository code instead.
• You need scale-out, HA, or heavy write throughput. That is a database and operations decision; the ORM wrapper is irrelevant and possibly obstructive.
• The team lacks graph modeling experience. Mis-modeled graphs produce worse performance than the SQL you left behind; budget for design review before adopting tooling.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a small set of roadmap features whose value comes from relationships — recommendations, permission inheritance, dependency and fraud analysis — that our relational database handles poorly. This MIT-licensed package lets us prototype graph capabilities inside our existing Laravel codebase, at effectively zero licensing cost and without hiring a new stack. The right ask is a timeboxed spike behind a replaceable interface, not a platform bet: it is a 10-star, single-maintainer dependency, so we adopt it as an experiment with an explicit exit path. If the spike proves the value, we decide separately whether to harden it, fork it, or move to the official driver.

For engineering (what to agree on before we start): We use this for model-shaped, read-heavy traversal work; Neo4j is a derived store, never the system of record, and no business transaction spans both databases. We keep all graph access behind our own repository/interface boundary so the package is swappable, and we pin the version and review the source before it touches production. Success criteria for the spike: the target feature implemented in days, query latency and code volume materially better than the SQL equivalent, and a written assessment of fork/maintenance cost. If any of those miss, we fall back to raw Cypher via the official driver or to the relational approach — and we call that a successful, cheap "no."