Neo4J Laravel Laravel Package

Getting Started

• Requirements: PHP 8.2+, Laravel 11/12/13. This is v0.0.1 — the first public release, so treat the API as unstable and pin the version.
• Configure the connection in config/database.php alongside your existing connections (a neo4j block with host, credentials, and auth mode). Because it's a real database driver, this is the natural first place to look.
• Keep sessions on file. Using Neo4j as the default connection does not support Laravel authentication — Laravel's session/user tables won't exist in the graph. Set SESSION_DRIVER=file and leave auth on a relational connection.
• First use case: confirm connectivity with the DB facade — DB::connection('neo4j')->select(...) or runCypher() — before layering the query builder or Eloquent on top. This validates driver config, TLS, and auth in one step.
• Inspect the primitives: ClientInterface, DriverInterface, SessionInterface, and TransactionInterface resolve from the container, so you can pull the raw driver/session for diagnostics or to drop down to driver-level calls.
• Then model your first node: define a Neo4jModel with a node label and use elementId() as the key.

Implementation Patterns

• Raw Cypher via DB: select(), insert(), update(), delete(), statement() for Laravel-shaped calls, plus read()/write()/runCypher() when you want explicit read/write intent (useful for routing and cluster behavior).
• Parameterized queries everywhere: write normal ? positional bindings and let the package map them to named $pN parameters. Booleans stay booleans, so you don't need the SQL-style 1/0 workarounds.
• Query builder for portability: Cypher is compiled through php-cypher-dsl. Reach for it for aggregates, date filters, groupBy, unions, and whereIn/whereExists subqueries — this is where you get Laravel ergonomics without hand-writing Cypher.
• Vector search: whereVectorSimilarTo() queries a Neo4j vector index. This is the headline pattern for semantic search / RAG features; pair it with application-level embedding generation.
• Graph relationships on the builder: matchRelationship() and insertRelationship(), including several matchRelationship() calls on a single query for multi-hop traversals.
• Bulk relationship writes: insertRelationships(), upsertRelationships(), syncRelationships(), deleteRelationships(). Use these in seeders and importers instead of looping single writes.
• Eloquent: Neo4jModel with a node label; standard relationship types (hasOne, hasMany, belongsToMany, hasOneThrough, hasManyThrough) plus full morph support (morphOne, morphMany, morphTo, morphToMany). Model-level matchRelationship() with create, attach, sync, detach mirrors familiar pivot workflows.
• Upserts: model upsert() plus the relationship upsert/sync variants for idempotent sync jobs.
• Transactions: beginTransaction/commit/rollBack for multi-statement writes, with connection and transaction timeouts configured per connection.
• Multiple connections: define several Neo4j connections, register one at runtime, and switch with useDatabase() — handy for multi-tenant graphs or environment isolation.
• Observability: hook Laravel query events for timing; the Debugbar collector gives per-request Cypher visibility; NEO4J_QUERY_CHANNEL controls per-request query log flushing for correlation in logs.

Gotchas and Tips

• Auth breaks on a Neo4j default connection. This is documented, not a bug. Keep SESSION_DRIVER=file and don't point AUTH at the graph.
• There is no id(). Neo4j nodes use elementId(). Anywhere you'd reach for $model->id, use the element id — don't assume integer auto-increment keys.
• Qualified timestamps are load-bearing. Timestamp columns are mapped into SET clauses as qualified names (User.updated_at → n.updated_at). If you customize timestamp handling, keep the qualification consistent or updates will write the wrong property.
• Cypher is not SQL. The builder covers a documented subset; features not listed may not translate cleanly. Fall back to runCypher() and centralize those queries so they're easy to audit and migrate.
• Bindings are rewritten. Positional ? becomes $pN in logs, slow-query output, and copied Cypher. Don't be surprised when the query you see isn't the query you typed.
• Vector indexes live outside the package. whereVectorSimilarTo() needs an actual Neo4j vector index; there's no migration support mentioned, so plan a Cypher DDL bootstrap step outside Laravel migrations for labels, indexes, and constraints.
• Multi-hop relationship matching is subtle. With several matchRelationship() calls on one query, verify the generated Cypher via Debugbar or query events before trusting the results.
• Config surface is broad — basic/Kerberos/OIDC/no-auth, SSL, pooling, connection and transaction timeouts. Get auth and TLS right first; those are the usual first-connect failures.
• v0.0.1 means churn. Pin the version, wrap direct driver usage behind small services, and use the container interfaces (ClientInterface, DriverInterface, SessionInterface, TransactionInterface) as seams for testing and future-proofing.
• Debug early, but understand log flushing. The Debugbar collector is the fastest feedback loop; remember NEO4J_QUERY_CHANNEL governs per-request flushing when you're correlating queries from logs.