Neo4J Laravel Laravel Package

Technical Evaluation

This package is a Laravel database driver and object-mapper layer for Neo4j, aimed at teams that want graph data access through familiar Laravel abstractions: DB, the query builder, Eloquent models, relationships, transactions, and query observability. Architecturally, it fits the Laravel service-container and database-manager model through ClientInterface, DriverInterface, SessionInterface, and TransactionInterface, and it compiles Laravel query-builder calls into Cypher via php-cypher-dsl. That is a reasonable integration point because it keeps most application code in Laravel idioms while translating only at the database boundary.

Integration feasibility is moderate to high for greenfield graph use cases and lower for existing relational applications. The release covers a broad surface for a first version: multiple connections, runtime connection creation, useDatabase(), parameterized queries, transactions, auth modes, SSL, pooling, timeouts, query events, Debugbar, vector similarity, and a fairly complete Eloquent relationship set including polymorphic and through relationships. That breadth is promising, but it also increases the review burden because each abstraction must be validated against real Neo4j behavior rather than assumed from Laravel relational semantics.

The main technical risk is maturity. This is v0.0.1, so API stability, edge-case correctness, and production hardening should be treated as unproven. Query-builder compilation to Cypher is a translation layer with semantic gaps: groupBy, unions, aggregates, subqueries, timestamps, relationship writes, and upsert behavior will not necessarily match Eloquent expectations. The explicit authentication limitation is significant: using Neo4j as the default connection does not support Laravel authentication, so sessions must remain on the file driver. Teams must avoid assuming Neo4j can back Laravel’s session/auth stack.

Key questions:

• Which Cypher features and Neo4j versions are officially supported and tested?
• What is the compatibility matrix across Laravel 11, 12, 13 and Neo4j server versions?
• How are schema migrations, indexes, constraints, and vector indexes managed?
• What is the test coverage and production-reference story for v0.0.1?
• How does the package behave when a Cypher translation cannot represent a Laravel query-builder construct?
• What is the upgrade/deprecation policy before a 1.0 release?

Integration Approach

The stack fit is strongest where Laravel is already the application framework and Neo4j is being introduced for graph-native use cases such as relationship-heavy domains, recommendations, dependency graphs, knowledge graphs, or vector-assisted retrieval. It is a poor fit as a drop-in replacement for a relational primary database in an existing Laravel app, especially where authentication, reporting, relational integrity, or mature migration tooling are central. The package should initially be introduced as a secondary connection for bounded graph workloads, not as the default application database.

The migration path should be incremental: add a dedicated Neo4j connection in config/database.php, keep sessions on the file driver, and build a small vertical slice using DB::connection('neo4j')->runCypher() or parameterized select/statement calls before adopting the query builder or Eloquent. After raw-driver behavior is validated, introduce one or two Neo4jModel classes and test relationship semantics, timestamps, and elementId() handling. Only then expand to relationship writes, bulk operations, polymorphic relationships, and vector queries. This sequencing limits exposure to translation-layer surprises.

Compatibility review should be explicit: PHP 8.2+, Laravel 11–13, Neo4j driver/server versions, auth modes, SSL, pooling, and timeout behavior. The php-cypher-dsl dependency should be reviewed for maintenance status, Cypher output stability, and escaping/parameterization behavior. Teams should avoid relying on undocumented Laravel query-builder parity and instead maintain a set of integration tests that assert generated Cypher and returned model behavior for critical paths.

Recommended sequencing:

1. Prove connectivity, auth, SSL, pooling, and transaction behavior in a non-production environment.
2. Validate parameter binding, booleans, timeouts, and query event/log behavior.
3. Pilot raw Cypher through runCypher() for core reads/writes.
4. Pilot query-builder support for simple selects, filters, aggregates, and unions.
5. Pilot Eloquent with one aggregate boundary and one relationship-heavy boundary.
6. Test vector index queries, bulk relationship writes, and upsert only after baseline stability.
7. Keep relational or file-backed components for auth/session and any unsupported Laravel features.

Operational Impact

Maintenance effort will be higher than a typical first-party Laravel database driver because this package owns a translation layer between Laravel abstractions and Cypher. Teams should expect ongoing work around dependency updates, Cypher generation changes, Neo4j driver upgrades, Laravel version compatibility, and regression tests for query-builder and Eloquent behavior. The v0.0.1 label implies API churn is likely; pinning versions and reviewing release notes before upgrades is essential.

Supportability depends on observability. The inclusion of Laravel query events, per-request query log flushing via NEO4J_QUERY_CHANNEL, and a Debugbar collector is a strong operational signal, but teams still need Neo4j-side monitoring, slow-query analysis, connection-pool metrics, and transaction timeout visibility. Because Cypher is generated rather than hand-written, support engineers will need a way to capture and inspect the final Cypher, parameters, and execution plan. Without that, debugging generated-query issues will be slow.

Scaling risk is concentrated in connection management, transaction scope, relationship-write batching, and vector-index query performance. The package advertises pooling, timeouts, multiple connections, and bulk relationship operations, which are the right primitives, but they must be load-tested against real workloads. Failure modes to plan for include Cypher translation errors for unsupported Laravel constructs, partial relationship writes, transaction rollback ambiguity, connection-pool exhaustion, timeout behavior under load, auth-mode misconfiguration, and accidental use of Neo4j for Laravel authentication despite the documented limitation. The session-driver constraint should be treated as a hard architectural rule, not a note.

Ramp-up is moderate for Laravel developers and higher for teams without graph experience. Developers can start with familiar DB and Eloquent patterns, but they must learn Cypher, graph modeling, relationship direction, index/constraint design, and the semantic differences between relational and graph queries. A pilot team should include at least one person comfortable reviewing generated Cypher. Documentation, examples, and failure-case guidance will materially affect adoption. For a v0.0.1 package, a bounded pilot with explicit exit criteria is more appropriate than broad production rollout.