Neo4J Php Client Laravel Package

Technical Evaluation

Architecture fit

• This is a driver, not an ORM. There is no Eloquent equivalent, no schema migrations, no model/relationship mapping, and no query builder for Cypher. In a Laravel codebase it occupies the same layer as a raw PDO/DB::connection() client, meaning the persistence abstraction, DTO hydration, and query ownership are ours to build.
• Best positioned as a secondary datastore alongside MySQL/Postgres for genuinely graph-shaped domains: permission/RBAC hierarchies, org-chart and entitlement traversal, recommendation and "similar item" features, fraud/entity-resolution rings, bill-of-materials, and knowledge graphs. It is a poor fit as the system of record for conventional CRUD.
• The API surface (client → driver → session → transaction) is small and explicit, which suits a service-layer or repository-pattern Laravel app. Auto-committed queries, transaction functions, and unmanaged transactions give us three clearly separable risk tiers.
• Framework friendliness is example-level only: the README points to a Laravel realworld example, but the package ships no service provider, facade, config stub, or health check. That is a small, well-understood integration cost for us, not a blocker.

Integration feasibility

• composer require laudis/neo4j-php-client, then wire a singleton Client into the container. Realistic build cost for a first working integration: 1–3 engineer-days, dominated by config/DI, connection verification, and a health check rather than the driver itself.
• Hard runtime prerequisites must be validated in CI and in every image: ext-bcmath, ext-json, ext-sockets, plus outbound TCP to Bolt (typically 7687) and TLS for bolt+s:///neo4j+s://. Serverless/FaaS and restricted-egress environments are a real risk here.
• Version matrix is tight and must be pinned deliberately: ^3.x requires PHP ^8.0 and supports Neo4j ^4.0, ^5.0; ^2.8 covers PHP 7.4/8.x against Neo4j 3.5/4.x. Legacy PHP applications cannot take latest.
• Positive supply-chain signal: built in collaboration with the official Neo4j driver team and validated against testkit, with full Psalm typing. This materially reduces "does it speak the protocol correctly" risk compared to a hobby driver.
• Negative signal: the HTTP/HTTPS drivers were removed in 3.3.0, so any environment that cannot do raw sockets has no supported fallback path.

Technical risk

• Ecosystem thinness. 188 stars and 0 listed dependents is a bus-factor and community-support concern for a component that would sit on a critical path. Mitigation is architectural, not contractual: hide the client behind our own GraphClient interface so substitution is a bounded change.
• Idempotency contract is easy to violate. Transaction functions auto-retry on transient errors; any side effect inside the closure (counters, dispatching jobs, emitting events, calling external APIs) will duplicate under retry. This is the single most likely production defect and needs a written convention plus code-review checklist.
• Result materialization and memory. Results come back as CypherList/CypherMap with typed Node/Relationship/Path objects and optional summarized metadata. Unbounded MATCH (n) RETURN n will exhaust PHP memory rather than stream; query-review discipline (LIMIT, pagination, projections) is mandatory.
• Type-boundary friction. Empty PHP arrays are ambiguous between Cypher list and map, requiring ParameterHelper; DateTimeInterface maps to DateTimeZoneId; Vector is decode-only. Each of these is a small, discoverable trap that belongs in a team style guide.
• Breaking-change history. A major-version jump already removed an entire transport. Treat minor upgrades as reviewable and major upgrades as planned work with integration tests against a real Neo4j instance.

Key questions

1. Do we actually need a graph database, or does Postgres recursive CTE / ltree satisfy the traversal workload at our scale? What query would be intractable otherwise?
2. Is Neo4j Aura (managed, auto-routed) or self-hosted/clustered? That determines whether we use bolt:// or neo4j:// and whether routing/leader-follower semantics matter to us.
3. What is the synchronization model from our relational system of record into Neo4j — dual-write, outbox/CDC, or batch ETL? Who owns reconciliation?
4. What Laravel runtime are we on (PHP-FPM, Octane, queue workers), and does each worker holding its own Bolt connections change our connection budget?
5. Do we need causal consistency across requests (bookmarks), or is eventual visibility acceptable?
6. Who owns Cypher authorship and review — application engineers or a data/graph specialist?
7. What is our acceptable support posture for a community package, and do we have a Neo4j commercial relationship to lean on?
8. Which Neo4j server versions must we support over the next 24 months, and does the ^3.x matrix (^4.0, ^5.0) cover our target including current 2025.x releases?

Integration Approach

Stack fit

• Laravel 10/11 on PHP 8.2+ against Neo4j 5.x on package ^3.x is the clean combination; anything older forces ^2.8 and constrains us to Neo4j 3.5/4.x.
• Natural integration shape:
  • config/neo4j.php reading drivers, URIs, credentials, and default alias from env.
  • A Neo4jServiceProvider registering the built client as a singleton and exposing a thin GraphClient interface (run, readTransaction, writeTransaction).
  • A repository/gateway per bounded context that owns Cypher strings and maps CypherMap/Node results into our own DTOs or Eloquent-backed read models.
  • php artisan neo4j:health plus a /health/graph probe using a trivial RETURN 1 or CALL db.ping().
• Keep the driver types out of controllers and domain code. Mapping Laudis\Neo4j\Types\Node directly into API responses couples our contract to the package and makes replacement expensive.

Migration path

• Greenfield features are the low-risk entry: add the graph for one read-heavy, traversal-shaped capability while relational writes stay untouched.
• From the predecessor graphaware/neo4j-php-client package: namespace-level rename to Laudis\Neo4j; mostly mechanical but touches every call site, so do it as an isolated, test-covered change.
• From removed HTTP/HTTPS drivers: not a config change. It requires network/socket enablement and a Bolt URI; budget this as infrastructure work, not a composer bump.
• From hand-rolled cURL calls to Neo4j's HTTP API: a genuine improvement (typed results, transactions, retries), and the natural moment to introduce the GraphClient seam.

Compatibility

• Pin the major version in composer.json, commit the lockfile, and gate upgrades behind integration tests against the exact Neo4j server version we run in production.
• Verify per environment: PHP extensions present, Bolt port reachable, TLS certificate chain valid for +s schemes, Neo4j user privileges adequate for the queries we issue.
• Confirm behavior on both transports if a cluster is in scope — auto-routed neo4j:// changes read/write targeting, so tests must cover readTransaction against a follower.

Sequencing

1. Spike (2–3 days). Prove connectivity from a Laravel container to a real Neo4j instance; validate extensions, TLS, and result hydration for our actual data shapes.
2. Foundation. Service provider, config, singleton binding, GraphClient interface, health check, Docker/CI service container.
3. Read path first. Ship one read-only capability (recommendations, hierarchy lookup) via readTransaction. Lowest blast radius, proves value, exercises type mapping.
4. Write path. Introduce writeTransaction with an idempotency review and a documented "no side effects inside the closure" rule; add retry-aware tests.
5. Asynchrony. Move heavy graph writes into queued jobs; verify connection behavior across worker processes.
6. Observability. Query timing via the summarized result metadata, error classification for transient vs terminal failures, connection-failure alerting.
7. Data sync. Only after the read/write paths are stable, formalize the relational→graph pipeline and its reconciliation job.

Operational Impact

Maintenance

• Low ongoing code maintenance: MIT license, typed API, small surface. The real recurring cost is version currency — PHP minor upgrades, Neo4j server upgrades, and package major bumps must be tracked as a scheduled backlog item, not discovered during an incident.
• We inherit ownership of anything the package does not provide: config, DI wiring, health checks, Cypher style guide, DTO mapping, and query performance review. That is perhaps 200–400 LOC of durable in-house code plus documentation.
• Because there are no migrations or schema tooling, graph constraints and indexes (CREATE CONSTRAINT, CREATE INDEX) need an explicit, versioned mechanism of our own — a plain Artisan command with idempotent Cypher is sufficient, but it must exist before go-live.

Support

• Community support via GitHub issues only; no SLA and no vendor escalation path on the library itself. The Neo4j driver-team collaboration and testkit validation are meaningful quality signals but are not a support contract.
• If the graph becomes business-critical, the practical insurance is (a) our GraphClient abstraction, (b) integration tests against a real server so a swap is verifiable, and (c) a Neo4j commercial relationship for the database side.
• Document a fork-and-patch contingency: MIT license makes an internal fork viable, but budget it as an unpleasant last resort, not a plan.

Scaling

• Connection lifecycle is per PHP process. Under PHP-FPM, each worker holds its own connections; sizing is a function of worker count, not request rate. Under Octane/Swoole, connections persist across requests, which improves throughput but makes connection and transaction leaks far more visible — test explicitly on whichever runtime we deploy.
• Use the auto-routed neo4j:// driver in clustered/Aura deployments and route reads through readTransaction and writes through writeTransaction to keep load off the leader.
• Push aggregation and traversal into Cypher rather than fetching subgraphs into PHP; the typed object graph is convenient and memory-hungry.
• Apply LIMIT, projections, and pagination as a hard convention. Prefer summarized results only where the metadata is actually consumed, since it adds per-query overhead.

Failure modes

• Duplicate side effects from retried transaction functions — the highest-probability defect. Detect via idempotency keys and reconciliation reports.
• Socket/extension absence in a new image or a locked-down environment: fatal at boot, not at query time. Catch with a startup health check.
• Transient cluster errors and timeouts surface as exceptions that bubble as 500s unless classified; introduce a mapping layer to distinguish retryable infrastructure errors from genuine client errors.
• Memory exhaustion from unbounded result sets — an availability incident with an obvious guardrail.
• Silent data divergence between the relational system of record and the graph, which surfaces as wrong recommendations or missing permissions rather than as errors. This needs monitoring, not just tests.
• Version drift: a Neo4j server upgrade past the tested range, or a PHP runtime upgrade that breaks a pinned major, discovered only at deploy time.
• Breaking-change surprise on minor/major bumps — the removal of HTTP drivers in 3.3.0 is the precedent; read release notes before any bump.

Ramp-up

• API fluency is fast: a mid-level PHP engineer can run queries and transactions within a day or two given the README's worked examples.
• The genuine ramp is Cypher and graph data modeling — traversal patterns, index/constraint design, and query plan reading. Budget 2–4 weeks for one engineer to become independently productive on non-trivial queries, and designate that person as the graph owner.
• The second ramp is correctness discipline: idempotent transaction functions, parameter typing (ParameterHelper, temporal types), and result-set bounds. Codify these as review checklist items and a short internal style guide at the time of the spike, not after the first incident.
• Recommend a half-day team session plus a living "Cypher patterns" document; most friction in the first months will be query shape and data modeling, not driver mechanics.