Neo4J Laravel Laravel Package

Product Decisions This Supports

• Feature bets on graph-shaped data. Multi-hop traversal, variable-depth paths, and relationship-heavy domains (social graphs, org/reporting hierarchies, permissions, product/catalog dependencies, fraud rings) are where Neo4j beats recursive SQL. This package lets those ship inside an existing Laravel codebase rather than as a separate service.
• AI/vector roadmap. whereVectorSimilarTo() against Neo4j vector indexes means semantic search and RAG-style retrieval can sit next to existing Eloquent models, rather than requiring a separate vector database vendor. This is a meaningful roadmap unlock in a first release.
• Build vs. buy on integration. The alternative is a bespoke Neo4j integration layer (connection handling, Cypher compilation, relationship persistence). A database driver, query builder compiled through php-cypher-dsl, and a Neo4jModel with hasOne/hasMany/belongsToMany/through and polymorphic relations is a lot of "buy" for free — but at v0.0.1 you are buying code, not support.
• Architecture decision: graph as a peer data store. config/database.php-level registration makes Neo4j a first-class connection alongside MySQL/Postgres. Multiple connections, runtime connection registration, and useDatabase() support multi-tenant or per-tenant-graph designs.
• Cost/latency decisions. Transactions, connection pooling, and connection/transaction timeouts are present, which is the minimum for putting graph writes behind a user-facing action. Per-request query log flushing (NEO4J_QUERY_CHANNEL), Laravel query events, and the Debugbar collector give the performance visibility needed to set and defend an SLO.
• A decision you must make early: Neo4j cannot back Laravel authentication or sessions as the default connection — sessions must stay on the file driver. That is an architectural constraint, not a bug, and it should be settled before any roadmap commitment that implies "single store."
• Bulk relationship operations (insertRelationships, upsertRelationships, syncRelationships, deleteRelationships) support backfill and reconciliation jobs, which is usually the difference between a demo and a shippable graph feature.

When to Consider This Package

Adopt (at least for a spike) when:

• The domain is genuinely graph-shaped — the questions you want to ask are "how is A connected to B," "who can reach this," "what is recommended via shared neighbors" — and SQL joins or recursive CTEs are already painful or projected to become so.
• The team is on PHP 8.2+ and Laravel 11, 12, or 13, with no near-term framework upgrade blocked by a pre-1.0 dependency.
• You want graph capability without a second application stack: same ORM idioms, same query-event plumbing, same Debugbar workflow.
• You need vector similarity search near existing relational models and would rather not operate a dedicated vector store.
• You are comfortable pinning a version, writing your own integration tests against your query patterns, and owning the upgrade path.

Look elsewhere when:

• Neo4j needs to be the single system of record for auth or sessions. Explicitly unsupported; plan for a split (relational or file-backed auth, graph for domain data) or pick a different architecture.
• You need full Eloquent parity today. The release notes cover models, relationship types, and relationship mutation — but say nothing about migrations/schema builder, soft deletes, global scopes, model events, eager-loading semantics, chunking, or pagination. Treat every unlisted Eloquent behavior as unverified until you test it.
• You need GA stability or vendor SLA. v0.0.1 with no published backward-compatibility policy is a pilot-grade dependency, not a platform commitment. If procurement requires supported software, this is not that.
• The team can't read Cypher. Queries are compiled from the Laravel builder via php-cypher-dsl; when something is slow or semantically wrong, someone must be able to read and hand-write Cypher. Budget for that skill.
• Data migration is in scope and unbudgeted. Nothing here migrates relational data into a graph. Modelling and backfill are your cost.
• Polyglot persistence is overkill. If two or three joins answer the question, adding a graph database adds operational surface for no product gain.

Also flag as unknowns to resolve in evaluation: supported Neo4j server versions, licence of the package and of php-cypher-dsl, maintainer/contributor depth, test coverage, and whether select() behavior matches Laravel 13 semantics beyond the note that it is compiled.

How to Pitch It (Stakeholders)

For executives. This is a first public release (v0.0.1) of a Laravel database driver for Neo4j. It lets the existing Laravel team build graph-backed and vector-search features — recommendations, relationship and permission traversal, semantic retrieval for AI — on the stack we already run, instead of standing up a separate service and a separate team. The strategic value is optionality: graph becomes an available tool rather than a re-platforming project. The risk is equally clear: it is pre-1.0, has no backward-compatibility promise, and cannot serve Laravel authentication or sessions. Recommendation: fund a time-boxed proof of concept on one relationship-heavy feature behind a feature flag, with an internal abstraction boundary, before any roadmap commitment.

For engineering. The surface is broad for a first release: a real DB driver with parameterised queries, transactions, pooling, TLS, and basic/Kerberos/OIDC auth; a query builder compiled to Cypher through php-cypher-dsl with aggregates, grouping, unions, subqueries, and vector similarity; Eloquent models with the standard relationship types including polymorphic and through-relations, plus relationship create/attach/sync/detach; and first-class observability via Laravel query events, per-request query log flushing, and a Debugbar collector. The gaps are maturity, not features: no migration tooling, unverified breadth of Eloquent parity, and an unresolved long-term maintenance story. Pin the version, wrap graph access behind our own repository interface, and validate our real query patterns and write paths in a spike before we depend on it.

For product. Ask for graph features only where the question is fundamentally about connections between things — that is where this earns its keep. Ask for vector search where we want semantic retrieval over content we already store. Don't ask for it as a general database replacement.