Bolt Laravel Package

Product Decisions This Supports

• Graph Database Integration: Enables PHP/Laravel applications to interact with Neo4j-compatible graph databases (e.g., Memgraph, Amazon Neptune, ArcadeDB, TuGraph) without proprietary drivers or REST APIs. Ideal for projects requiring high-performance, low-latency graph queries (e.g., recommendation engines, fraud detection, knowledge graphs).
• Build vs. Buy: Buy for teams needing Bolt protocol support (vs. building from scratch) but build if requiring custom extensions (e.g., advanced query parsing, real-time analytics).
• Roadmap Alignment: Critical for:
  • Data-intensive apps migrating from relational to graph databases.
  • Microservices needing graph traversals (e.g., supply chain, social networks).
  • Hybrid architectures combining Laravel’s ORM with graph queries.
• Use Cases:
  • Real-time analytics: Low-latency graph traversals (e.g., dynamic pricing, network analysis).
  • Legacy system modernization: Integrate graph queries into existing PHP/Laravel apps.
  • Multi-database strategies: Unified access to Neo4j, Memgraph, Neptune, ArcadeDB, TuGraph, and Grafeo via Bolt.
• Operational Maturity (v7.5.0): PSR-3 logging integration and bookmarks support (causal consistency / cluster routing) remove two common blockers for productionizing graph workloads—observability and read-your-writes across clustered deployments.

When to Consider This Package

Adopt if:

• Your Laravel app requires direct Bolt protocol access (not REST/HTTP) for graph databases.
• You need support for Bolt up to 6.1 (e.g., Neo4j 5.x/2025.x, Memgraph, ArcadeDB, TuGraph) with PHP 8.1+.
• Your use case involves high-throughput graph operations (e.g., batch processing, complex traversals).
• You need causal consistency or cluster-aware reads — v7.5.0 adds bookmarks support, which prior versions lacked.
• Your platform team expects PSR-3 compatible logging (v7.5.0) to plug into Laravel’s Monolog stack.
• You’re avoiding vendor lock-in (works with Neo4j, Memgraph, Neptune, ArcadeDB, TuGraph, Grafeo, etc.).
• Your team lacks expertise in low-level TCP/socket programming for Bolt.

Look elsewhere if:

• You’re using Neo4j’s official PHP driver (preferred for Neo4j-specific features).
• Your database doesn’t support Bolt (e.g., PostgreSQL with pg_graph).
• You need high-level abstractions (e.g., Eloquent for graphs; consider Laravel Neo4j).
• Your app is REST-only (use Neo4j’s HTTP API instead).
• You require real-time subscriptions (Bolt lacks WebSocket support; use Neo4j’s driver).

Upgrade watch-outs for v7.5.0:

• Do not set PackStream version manually — the setter is deprecated; PackStream is now coupled to the Bolt version (Bolt 6.1). If your app called this setter directly, remove the call.
• AProtocol constructor signature changed — safe if you obtain the protocol via Bolt::build() (recommended path); direct instantiation will break.
• Internal autoload.php removed — confirm you’re relying on Composer autoload (standard for Laravel).

How to Pitch It (Stakeholders)

For Executives: "This package lets us leverage graph databases (like Neo4j, Memgraph, or ArcadeDB) directly from PHP/Laravel, unlocking real-time, high-performance queries for use cases like fraud detection or recommendation engines. It’s a drop-in Bolt driver—no REST overhead, no vendor lock-in—while keeping our stack PHP-native. The latest release (v7.5.0) adds cluster-aware bookmarks and standard PSR-3 logging, which means we can run it in production multi-node deployments and feed logs into our existing observability stack instead of building that ourselves. It also expands tested compatibility to ArcadeDB, TuGraph, and Grafeo, giving us negotiating leverage and exit options across vendors. For example, we could replace slow SQL joins with millisecond graph traversals, cutting latency dramatically in scenarios like supply chain optimization. The MIT license and active maintenance (last release: 2026-03) make it a low-risk choice."

For Engineering: *"This is a low-level Bolt client for PHP 8.1+, now supporting Bolt 6.1. Key benefits:

• Direct TCP socket access to graph databases (Neo4j, Memgraph, ArcadeDB, TuGraph, etc.) with pipelining for efficiency.
• Transaction support (begin/commit/rollback), auth schemes (Basic, Bearer, Kerberos), and now bookmarks for causal consistency across cluster reads.
• PSR-3 compatible logger — drop-in integration with Laravel/Monolog; no custom logging plumbing.
• New query method and UnsupportedType structure for gracefully handling unknown protocol types.
• PackStream serialization for complex data (lists, dictionaries, structures).
• No dependencies beyond PHP’s mbstring/sockets (optional OpenSSL). Migration notes for v7.5.0: The AProtocol constructor signature changed (non-breaking if you use Bolt::build()), the ability to manually set the PackStream version is deprecated (it’s now tied to Bolt version), and the internal autoload.php was removed (Composer handles it). Use case: If we’re building a Laravel service for graph analytics, this avoids REST latency, lets us issue Cypher queries natively, and now supports cluster-consistent reads. Tradeoff: More control but less abstraction than Neo4j’s official driver. Pair with a helper layer (e.g., Laravel service) to hide Bolt complexity."*

For Developers: *"Need to query Neo4j/Memgraph/ArcadeDB from PHP without REST? This package gives you raw Bolt 6.1 protocol access with:

• Protocol-aware methods (run(), pull(), begin()) matching Bolt specs, plus a new query method for convenience.
• Bookmarks support — pass/return bookmarks to get read-your-writes guarantees in clustered setups.
• PSR-3 logger hook — pass any PSR-3 logger (e.g., Laravel’s Log) and Bolt traffic/debug events flow into your normal log pipeline.
• Pipeline support for batch queries.
• Type safety for Cypher parameters (Bytes, Lists, Dictionaries), plus an UnsupportedType wrapper so unknown wire types don’t blow up. Example: Replace DB::select() with $bolt->run('MATCH (n) RETURN n')->pull() for graph data. Upgrade checklist: stay on Bolt::build() (don’t touch AProtocol constructor directly), remove any setPackStreamVersion() calls, and delete any references to the old internal autoload.php. Docs link to Neo4j’s Bolt specs for version-specific details. Start with the Client helper class to simplify boilerplate."*