Neoeloquent Laravel Package

Product Decisions This Supports

• Graph-shaped feature bets: NeoEloquent is an Eloquent-style ORM for Neo4j, so it lets the team ship graph-native features — recommendation/similarity ("people who bought X"), fraud and anomaly rings, permission/entitlement hierarchies, social/follow graphs, knowledge graphs, dependency and lineage models — without a separate data-access layer or a second application stack.
• Build vs. buy for graph persistence: if a roadmap item needs multi-hop traversal (variable-depth paths, shortest path, cycle detection) that would otherwise become recursive SQL or a nightly denormalization job, this package is the cheap path to evaluate. If the need is "a few joins and some reporting," it is not.
• Platform/version policy: v9.9.0 hard-drops Laravel 10 and 11 and requires Laravel 12/13 on PHP 8.2+. Apps on 10/11 are pinned to 9.8.x by Composer rather than breaking — so this is a scheduling decision, not an outage. It puts NeoEloquent on the critical path of any Laravel upgrade: the framework upgrade and the graph layer upgrade ship together.
• Neo4j 5 as the supported target: the hasOne()/belongsTo() fix without an explicit relationship type removes a friction point for teams modeling on Neo4j 5, which matters if the database platform has already been standardized there.
• Soft-delete semantics now trustworthy on Laravel 13: SoftDeletes, onlyTrashed(), and counts working means "delete" in graph entities can follow the same product rules as the relational side — auditability, undo, retention windows — instead of being a bespoke flag the graph layer ignores.

When to Consider This Package

Consider it when all of the following hold:

• The domain is genuinely relationship-first: traversal depth is a product feature, not an analytics afterthought.
• The team has committed (or is seriously evaluating) Neo4j 5 as a system of record or a co-primary store — this package is an adapter, not a reason to adopt a graph database.
• The application is on, or is actively moving to, Laravel 12/13 with PHP 8.2+. Adoption on Laravel 10/11 is a dead end: you would be starting on a branch that receives no further fixes.
• Developers are already fluent in Eloquent and you value graph access that looks like models and relationships rather than raw Cypher in every call site.
• You accept a single-maintainer dependency for a component touching core data access, and are willing to pin versions and read changelogs before upgrading.

Look elsewhere when:

• The graph requirement is really reporting or search — a relational store plus a search index, or a managed graph service with its own SDK, will be less work.
• You need dual-write consistency guarantees between SQL and Neo4j. The package does not make cross-store transactions a solved problem, and that gap is architectural, not something a version bump closes.
• You are on Laravel 10/11 with no upgrade date — you would be adopting a frozen line.
• You require vendor support, SLAs, or a broad contributor base. The migration from Travis to GitHub Actions and the "test suite fixed and made deterministic" note are welcome, but they also signal infrastructure that is still maturing.
• Your workload is heavy write-throughput or bulk ingest; verify performance against your own numbers before committing.

How to Pitch It (Stakeholders)

To executives: We evaluated NeoEloquent, the Laravel integration for the Neo4j graph database. The new release (v9.9.0) aligns it with our current framework generation — Laravel 12/13, PHP 8.2+ — and fixes real correctness bugs, notably soft deletes and default relationship handling. It is a narrow, low-cost enabler: it lets us build relationship-heavy features (recommendations, fraud detection, permissions, knowledge graphs) inside the stack we already run, instead of adding a second application platform. The trade-off is concentration risk — one primary maintainer — and the requirement that the graph layer upgrades in lockstep with Laravel. Recommendation: adopt only where a roadmap item genuinely needs multi-hop traversal, pin the version, and treat every Laravel upgrade as including a NeoEloquent compatibility check. Note that apps still on Laravel 10/11 are unaffected — they remain on the 9.8 line — so there is no forced migration, but also no future fixes on that line.

To engineering: v9.9.0 is a breaking release gated on Laravel 12/13 and PHP 8.2+; Composer will hold Laravel 10/11 apps on 9.8.x automatically, so the upgrade is a deliberate version bump, not an accident. It fixes soft deletes (SoftDeletes, onlyTrashed(), counts) on Laravel 13 and hasOne()/belongsTo() without an explicit relationship type on Neo4j 5 — both were sharp edges worth knowing about. CI has moved from Travis to GitHub Actions across PHP 8.2–8.5 and Laravel 12–13 on Neo4j 5.26, and the test suite is now deterministic. Before adopting: confirm your Neo4j server version, decide explicitly how SQL↔Neo4j consistency will be handled, and budget for reading changelogs on every bump given the single-maintainer bus factor. Keep the package version pinned and the graph layer covered by our own integration tests rather than relying solely on upstream's suite.