Neo4J Bolt Laravel Package

Technical Evaluation

• Architecture fit: Poor for greenfield Laravel work. graphaware/neo4j-bolt is a low-level PHP client speaking Neo4j’s Bolt binary protocol — not a Laravel-native graph abstraction. It ships no service provider, facade, config, or Eloquent coupling, so the TPM should treat it as a protocol primitive that must sit behind an explicit repository/adapter boundary. It fits only legacy PHP services already pinned to Neo4j 3.x-era Bolt, not a modern Laravel domain layer.
• Integration feasibility: Composer-installable in principle, with a permissive MIT license, but the repository is archived, has 42 stars, zero dependents, and a low package score. That combination signals weak community validation and no realistic upstream maintenance. Practical wiring means hand-rolled configuration, manual service-provider binding, and explicit connection lifecycle management — all of which become internal product surface, not off-the-shelf integration.
• Technical risk: High. Archived status means no security patches, no Bolt protocol updates, and no guaranteed PHP 8+/Laravel 10+ support; composer require may need --ignore-platform-reqs, which is a stopgap, not a fix. Bolt is versioned, so server/protocol drift can cause hard failures. Authentication, TLS, transactions, connection pooling, and error semantics all require independent validation. The static GraphDatabase::createDriver() factory opens a socket immediately and resists clean test seams until wrapped.
• Key questions: Which Neo4j and Bolt protocol versions must be supported, and is graph traversal genuinely core enough to justify Neo4j over relational, JSON, or search-backed storage? Is the target PHP/Laravel version compatible, or will an owned fork be required? Can the driver be isolated behind a Neo4jClient interface from day one? What is the funded exit date and owner for migrating to a maintained client (laudis/neo4j-php-client) or Neo4j’s HTTP API? What is the security and vendor-review posture for shipping an archived dependency into revenue-critical paths?

Integration Approach

• Stack fit: Weak for standard Laravel. The only defensible pattern is an adapter: define a Neo4jClient contract, implement it with the Bolt driver, map GraphAware\Bolt\Result\Type\Node/Relationship/Path objects into DTOs, and keep hand-written Cypher inside repository classes. Never let Bolt types, sessions, or Cypher strings leak into controllers, jobs, Blade views, or domain code. Use scoped() rather than singleton() when binding the driver so Octane and queue workers don’t inherit stale sockets.
• Migration path: Treat this as a time-boxed bridge, not a foundation. Inventory existing Neo4j usage, pin the exact package commit, wrap every call behind the interface, add contract tests against the target Neo4j version, run parallel read-only queries against the maintained client, cut over, then remove the package entirely.
• Compatibility: Validate PHP constraints, Laravel discovery behavior, Bolt protocol version, Neo4j auth/TLS, transaction APIs ($session->transaction() may be absent in early 1.x pins, which means no client-side transaction control), and any PHP extension requirements. Add a CI matrix spanning supported PHP, Laravel, and Neo4j (e.g. neo4j:3.5) versions so you test against the Bolt protocol you actually ship. Do not claim compatibility without integration tests.
• Sequencing: 1) Time-boxed proof of concept against the target Laravel and Neo4j versions. 2) Security, license, and dependency audit. 3) Build the adapter, fake for tests, and contract suite. 4) Enable limited read-only usage behind Cache::remember for hot traversals. 5) Add write paths in queued jobs with explicit transaction tests. 6) Publish an operational runbook. 7) Fund and schedule the replacement. Gate the project hard if protocol or PHP compatibility fails — that is a stop signal, not a backlog item.

Operational Impact

• Maintenance: High internal burden. Archived upstream means fork ownership, dependency pinning, CVE response, PHP upgrade work, Bolt protocol changes, and Neo4j compatibility testing all become internal responsibilities. Zero dependents means little community troubleshooting when something breaks at 2 a.m., so budget for a named owner rather than “the platform team.”
• Support: No vendor support. A single accountable engineer should own graph connectivity, upgrades, and incident response; if that role can’t be funded, the package should not ship. Avoid revenue-critical use without a documented patch budget and a tested fallback path to a maintained driver or the Neo4j HTTP API.
• Scaling: The driver is not the scaling lever — Neo4j cluster design and Cypher performance dominate. Expect the client to lack pooling, retry, and observability that production Laravel workloads assume, and benchmark connection churn, latency, transaction throughput, and large-result streaming under queue/worker concurrency before committing SLOs. Keep Bolt calls off the request path where blocking behavior risks user-visible latency.
• Failure modes: Bolt protocol mismatch, auth/TLS failures, dropped connections, transaction leaks from abandoned sessions without finally { $session->close(); }, unbounded result sets from unparameterized lookups, ProtocolException from unsupported parameter types (DateTime, enums, Eloquent models), PHP fatal incompatibilities, and duplicate writes from naive retries. Mitigate with health checks, timeouts, circuit breakers, structured logs, query-level metrics, and strict {name} parameterization to prevent Cypher injection.
• Ramp-up: The API is small (GraphDatabase, Driver, Session, Result, Record), but the team still needs Neo4j, Cypher, Bolt, transaction, and graph-modeling expertise plus awareness of the {name} placeholder syntax that differs from the maintained successor. Expect moderate ramp-up for PHP developers, higher operational risk for SRE, and cross-training debt if only one engineer knows the driver. Onboarding artifacts — runbooks, contract tests, and the exit plan — should land before the first production write.