Neoeloquent Laravel Package

Technical Evaluation

Architecture fit: NeoEloquent is a graph-database adapter that lets Laravel applications use Eloquent-style models against Neo4j. It fits best where Neo4j is already a deliberate part of the architecture — recommendation engines, fraud rings, knowledge graphs, dependency graphs — and the team wants to avoid maintaining a separate query layer. It is not a drop-in replacement for a relational Eloquent model; graph traversal, relationship direction, and Cypher semantics still shape the domain model. This release does not change that positioning.

Integration feasibility: The package remains installable via Composer and is constrained to Laravel 12–13 and PHP 8.2+. For applications already on that matrix, integration is straightforward: add the service provider, configure the Neo4j connection, and define graph-backed models. For applications on Laravel 10/11, Composer will resolve to 9.8.x, so there is no forced break — but also no new fixes. Feasibility depends more on Neo4j operational readiness (5.26 cluster, auth, backups) than on the package itself.

Technical risk: The breaking change is a support-window drop, not an API rewrite, which lowers immediate risk. The more material risks are: (1) the package’s compatibility matrix is narrow — only Neo4j 5.26 is tested, so older Neo4j 5.x or 4.4 deployments are unverified; (2) soft-delete and relationship-inference fixes indicate that Laravel-version and Neo4j-version-specific query translation remains fragile; (3) the project appears community-maintained, with a small contributor base and a recent CI migration, so long-term support depth is unclear; (4) teams may silently remain on 9.8.x without realizing they are outside the maintained line.

Key questions:

• Is Neo4j 5.26 the only supported server version, or is the CI matrix merely a representative target?
• What is the support policy for 9.8.x now that Laravel 10/11 are dropped — security fixes only, or end-of-life?
• Who owns maintenance, and what is the release cadence and backward-compatibility posture?
• Does the test suite cover soft deletes, polymorphic relationships, and hasOne/belongsTo inference across both Laravel 12 and 13?
• Are there known Cypher-generation differences between Neo4j 5.26 and earlier 5.x releases that affect production behavior?

Integration Approach

Stack fit: Best fit is a Laravel 12/13 application on PHP 8.2–8.5 with a Neo4j 5.26 backend used for a bounded graph workload — not as the primary system of record unless the team has Cypher and graph-modeling depth. The package complements, rather than replaces, relational Eloquent usage.

Migration path: For Laravel 10/11 applications, do nothing immediately: keep 9.8.x pinned, confirm Composer resolution, and schedule the framework upgrade separately. For Laravel 12/13 applications, upgrade the package to ^9.9 and run the integration suite against Neo4j 5.26. Treat the framework upgrade and package upgrade as one change window; do not upgrade the package ahead of the framework, because Composer will block it.

Compatibility: The supported matrix is PHP 8.2–8.5 × Laravel 12–13 × Neo4j 5.26. Confirm PHP 8.5 availability in the build image before claiming full matrix coverage; if production is on 8.2/8.3, test there explicitly. Confirm Neo4j server patch level, since only 5.26 is exercised in CI.

Sequencing:

1. Inventory Laravel, PHP, and Neo4j versions across applications and services.
2. Audit graph models for soft deletes, onlyTrashed(), trashed counts, and hasOne/belongsTo relationships without explicit relationship types — these are the areas the release fixes.
3. Upgrade Laravel to 12 (or 13) first, with the package still on 9.8.x.
4. Upgrade NeoEloquent to ^9.9 and run application-level graph integration tests against Neo4j 5.26.
5. Validate CI/CD and local development parity, since the project moved from Travis to GitHub Actions.
6. Document the pinned version per application and add a dependency-review check so teams do not drift onto an unsupported line silently.

Operational Impact

Maintenance: The Travis-to-GitHub-Actions move is a positive maintenance signal; Travis is largely deprecated, and a deterministic test suite improves release confidence. However, the project still appears thinly staffed, so maintenance risk is moderate. Teams should expect to validate releases themselves rather than rely on upstream coverage for their exact Neo4j topology.

Support: The 9.8.x line is now the de facto legacy branch. If the project does not backport fixes, Laravel 10/11 users face a slow security and bug-fix gap. Plan framework upgrades with that in mind rather than treating 9.8.x as a long-term home.

Scaling: The package is a driver, not a scaling layer; throughput and latency will be dominated by Neo4j cluster design, Cypher query shape, and Eloquent hydration overhead. Graph queries that look harmless in Eloquent can produce unbounded traversals. Add query review, pagination limits, and profiling for graph-backed endpoints. Eager-loading behavior across graph relationships should be tested explicitly rather than assumed from relational Eloquent experience.

Failure modes:

• Composer silently resolving to 9.8.x on Laravel 10/11, creating invisible version skew across services.
• Cypher translation regressions tied to a specific Laravel or Neo4j version — the soft-delete fix on Laravel 13 is a direct example.
• Relationship inference failures for hasOne/belongsTo without explicit types on Neo4j 5.
• CI coverage limited to Neo4j 5.26, leaving earlier 5.x deployments untested.
• Single-maintainer or small-contributor risk affecting release cadence and security response.

Ramp-up: Developers familiar with Eloquent will onboard quickly on model definition, but graph modeling, relationship direction, Cypher debugging, and transaction semantics require deliberate training. Budget for a short graph-data-modeling workshop and a review checklist before teams build production features on the package.