Neo4J Bolt Laravel Package

Technical Evaluation

Architecture fit: plumtreesystems/neo4j-bolt is a low-level PHP driver for Neo4j’s Bolt binary protocol, not a Laravel-native package. It does not provide a service provider, facade, configuration publishing, Eloquent-style models, or Laravel-oriented query builder. It can fit a Laravel application only if graph access is isolated behind an internal adapter/repository layer and the team explicitly wants direct Cypher-over-Bolt access.

Integration feasibility: Feasible for a narrow proof of concept, but not a drop-in Laravel integration. Work would include Composer/version constraints, connection lifecycle management, authentication/TLS configuration, transaction handling, result mapping, exception translation, and health checks. The package’s age and low adoption mean integration effort is dominated by compatibility validation rather than feature configuration.

Technical risk: High. The last release was 2020, the project has 11 stars and zero dependents, and there is no evidence of active maintenance. Bolt protocol compatibility with modern Neo4j versions is the primary risk, followed by PHP 8.x/Laravel 9+/10+/11 compatibility, sparse documentation, unclear test coverage, and no demonstrated security-response process. MIT licensing is favorable, but production use likely implies internally owning or forking the driver.

Key questions:

• Which Neo4j versions and Bolt protocol versions must be supported?
• Which PHP and Laravel versions are in scope, and is PHP 8.2+ required?
• Are transactions, routing, causal consistency, TLS, and Neo4j cluster support required?
• Is there a maintained official or community PHP driver that better fits the target Neo4j version?
• Who will own patching/forking if upstream is inactive?
• What is the acceptable migration/exit path if Bolt compatibility breaks?

Integration Approach

Stack fit: Best suited as an infrastructure adapter inside a Laravel service, job, or console command—not as a domain model layer. Expose a small internal interface such as GraphClient with methods for runQuery, transaction, and healthCheck, keeping the package behind that boundary. Configure via environment variables and a singleton connection managed by Laravel’s container.

Migration path: Start with a time-boxed spike against the exact target Neo4j version. Pin the package version and wrap it immediately. If the spike passes, use a strangler-style rollout: one bounded graph use case, staging validation, then canary traffic. Maintain a fallback path to Neo4j’s HTTP API or a maintained PHP driver. Avoid spreading raw Bolt/driver calls across the codebase.

Compatibility: Build a compatibility matrix before commitment: PHP version, Laravel version, Composer resolution, Neo4j server version, Bolt protocol version, auth/TLS settings, and required Cypher features. Validate PHP-FPM and queue-worker behavior separately. Treat Laravel 9+ and PHP 8.x support as unproven until tested.

Sequencing:

1. Audit package source, tests, open issues, and PHP/Neo4j compatibility.
2. Run a non-production proof of concept with the target Neo4j deployment.
3. Implement the internal adapter, configuration, exception mapping, and health check.
4. Add integration tests for auth, TLS, transactions, timeouts, and failure recovery.
5. Load-test connection behavior under PHP-FPM and queue workers.
6. Canary one use case with rollback criteria and a documented exit plan.

Operational Impact

Maintenance: Expect to self-maintain. The package is likely to require pinned dependencies, internal patches, and periodic compatibility checks. Budget engineering time for fork ownership, dependency updates, and security review. MIT license reduces legal friction but does not reduce operational ownership.

Support: Community-only support with limited evidence of active maintainers. Production use should have a named internal owner, runbooks, escalation path, and a tested fallback to an alternative driver or Neo4j HTTP API.

Scaling: Uncertain without load testing. PHP’s request model means connection lifecycle and pooling must be managed carefully, especially across PHP-FPM workers and Laravel queues. Neo4j cluster routing, causal consistency, and result streaming behavior should be explicitly tested if scale or HA is required.

Failure modes: Bolt protocol mismatch after Neo4j upgrade, PHP/Laravel incompatibility, authentication/TLS failures, connection exhaustion, query timeouts, partial transaction handling, large-result memory pressure, and untranslated driver exceptions leaking into Laravel error handling. Monitoring should cover connection count, query latency, error rate, timeout rate, and Neo4j server health.

Ramp-up: Moderate to high. Developers need Neo4j/Cypher and Bolt fundamentals in addition to Laravel experience. Low adoption and sparse documentation increase onboarding time. A narrow adapter layer and internal examples can reduce ramp-up, but the team should assume ownership of driver behavior rather than relying on upstream guidance.