Neo4J Bolt Laravel Package

Technical Evaluation

What this actually is. Despite the framing, anyitsolutions/neo4j-bolt is not a Laravel package. It is a low-level, pure-PHP implementation of Neo4j's binary Bolt protocol — PackStream serialization, handshake negotiation, chunked message framing, and the request/response state machine. There is no service provider, no facade, no config file, no Eloquent driver, no query builder, and no relationship/entity mapping. Everything above the wire — connection lifecycle, Cypher parameter binding ergonomics, result hydration, transactions, retries — is application code you would own. That distinction drives every conclusion below.

Architecture fit. Bolt is a stateful, connection-oriented protocol, which sits awkwardly against PHP-FPM's share-nothing request model. Every request means a TCP connect, a version handshake, an auth round-trip, and a clean disconnect — typically single-digit to low-tens of milliseconds of pure overhead before a single Cypher statement runs. That is tolerable for low-volume admin or reporting paths and corrosive for hot request paths. A graph layer built on this package is therefore best positioned as a bounded-context service behind an internal adapter interface, not as a general-purpose persistence layer woven through controllers.

Integration feasibility. Mechanically straightforward in isolation: composer require, instantiate a connection, run Cypher, decode results. The real cost is that the package stops at the socket. You must build: a connection abstraction, transaction/commit semantics, error classification (transient vs. fatal), TLS configuration if required, and result-to-DTO mapping. Rough estimate: two to four engineer-weeks before it is production-shaped, versus roughly two to three days to stand up the equivalent against Neo4j's HTTP transactional endpoint using Guzzle — at the cost of higher per-query latency and no streaming.

Technical risk — this is the deciding factor. The package's last release was 2020-08-11. That date is disqualifying on its own for a protocol client, because Bolt is versioned and negotiated: Neo4j 5.x rejects handshakes that do not offer a sufficiently recent Bolt version, and a driver frozen in 2020 predates Bolt 4.1+ and the entire 5.x line. Confidence that it connects to a current Neo4j server is low, and unverified. Secondary risks compound it:

• Zero dependents, one star. No production signal, no issue history to mine for known failure modes, no evidence of anyone running this against a modern server.
• PHP 8.x compatibility unknown. Code from that era commonly carries untyped properties, dynamic-property usage, and deprecated patterns that surface as fatal errors or deprecation noise on 8.1+.
• Bus factor of one. MIT license means you can fork and maintain it, but you would be adopting a protocol implementation — a category where correctness bugs are subtle and expensive.
• No security disclosure path and no patching cadence. A vulnerability in PackStream or TLS handling would not be fixed upstream.

Key questions for the team. (1) What Neo4j server version is actually deployed, and does this driver's handshake negotiate successfully against it — proven, not assumed? (2) Why a graph database at all: is the access pattern genuinely traversal-heavy, or would Postgres with recursive CTEs satisfy it? (3) If graph is justified, why not laudis/neo4j-php-client (actively maintained, supports Bolt and HTTP) or stefanak-michal/bolt (maintained protocol layer) rather than an abandoned one? (4) Who owns this code if the original author is unreachable, and is that person staffed? (5) Does the workload tolerate per-request connection establishment, or does it need pooling that PHP cannot provide?

Verdict. Do not adopt as a dependency. The protocol-version gap alone makes it a likely non-starter against any supported Neo4j release, and the surrounding risk profile — abandoned, unvalidated, single-maintainer, zero downstream users — is unjustifiable for infrastructure. Re-evaluate only if a spike proves a clean handshake and query round-trip against the target server version and the team accepts permanent ownership of a forked protocol implementation.

Integration Approach

Stack fit. Poor as a Laravel citizen, adequate as a raw client. Laravel's conventions assume a driver can be bound into the container and swapped via config; this package offers nothing to bind, so you would write the service provider, the config surface, the connection singleton, and the health check yourself. It has no relationship to Eloquent, so any expectation of $user->friends()-style traversal must be abandoned — graph access will be an explicit repository call, deliberately outside the ORM.

Migration path. Because the package is not a driver in any framework sense, "migration" is really "build a bounded adapter." Concretely:

1. Define an internal GraphClient interface with the narrow surface you actually need — run(string $cypher, array $params): ResultSet, beginTransaction(), close(). Nothing else.
2. Implement Neo4jBoltGraphClient against this package, confining every reference to the dependency to this one class.
3. Implement a second adapter against Neo4j's HTTP transactional endpoint using the HTTP client already in the stack. This is your fallback and your comparison baseline.
4. Bind via a service provider reading config/graph.php, so swapping implementations is a config change, not a refactor.

This costs perhaps three extra days and converts an irreversible bet into a reversible one — the single highest-leverage decision in the whole engagement.

Compatibility. Verify against the deployed Neo4j version, not a local container. Pin an exact server version in the spike environment. Explicitly test: handshake negotiation, authentication (basic and, if used, bearer), parameter type round-tripping (temporal and spatial types are common Bolt breakage points), TLS if the connection crosses a network boundary, and behavior when the server restarts mid-session. Confirm PHP 8.1/8.2/8.3 compatibility by actually running the test suite — if there is no suite, that is itself a finding.

Sequencing. Do not parallelize discovery with build. (1) Two-day spike: handshake + one parameterized read + one write against the target server version, on the target PHP runtime. Gate decision here. (2) If green, build both adapters behind the interface. (3) Contract tests that run identically against both adapters — this is what keeps the abstraction honest. (4) Ship the HTTP adapter to production first for a low-risk internal use case; the Bolt adapter follows only if latency data justifies it. (5) Only then consider hot-path usage.

Operational Impact

Maintenance. Total. The package is effectively archived; every bug, PHP-version break, and Neo4j protocol change lands on your team. Budget roughly 10–15% of one engineer's capacity in steady state for a forked protocol implementation, spiking sharply at every Neo4j major upgrade. This is a permanent, non-amortizing cost — it does not diminish as the team gains familiarity, because the churn comes from outside.

Support. None. No vendor, no SLA, no maintainer responsiveness to assume. The mitigation is a fork under your own namespace with a documented ownership assignment and a quarterly review against upstream and against Neo4j's protocol changelog. If nobody will accept that assignment, the answer is no.

Scaling. Constrained by architecture rather than by the package. PHP-FPM gives no connection reuse, so throughput ceiling is roughly 1 / (handshake + auth + query latency) per worker process — you scale by adding workers, which adds connection churn on the database side and eventually saturates Neo4j's connection handling. Queue workers and Octane long-running processes are the opposite problem: a held Bolt connection must survive server restarts, idle timeouts, and network partitions, and this library almost certainly does not implement heartbeat or reconnect. Both paths need work the package does not provide.

Failure modes to instrument for. Handshake rejection on server upgrade (silent, deploy-time, total outage for graph features); unhandled disconnects surfacing as opaque socket errors rather than retryable exceptions; partial transaction state left open on the server when a PHP process dies mid-transaction; connection exhaustion under load; and type-mapping mismatches on temporal/spatial values that corrupt data quietly rather than failing loudly. Each needs a specific alert and a documented runbook entry, and the transaction-orphan case in particular needs a server-side dbms.listTransactions cleanup procedure.

Ramp-up. Steeper than the package's small API surface suggests. Engineers need three distinct competencies: Cypher and graph data modeling (a genuine paradigm shift for teams raised on relational thinking), Neo4j operational semantics (indexes, query plans, memory configuration), and — because this is a protocol implementation rather than a client — enough Bolt and PackStream familiarity to debug at the byte level when something goes wrong. The third is rare and non-transferable. Realistic ramp-up is two to three weeks before an engineer is independently productive, plus one person designated as the deep owner who reads the Bolt specification itself. A maintained client library removes that third requirement entirely, which is the strongest practical argument against this package.