Weave Code
Neoeloquent Laravel Package
vinelab/neoeloquent
NeoEloquent brings Eloquent-style models to Neo4j in Laravel. Define graph nodes and relationships as expressive PHP classes, use familiar query building and eager loading, and work with Cypher-backed graph data without leaving Laravel's ORM conventions.
The Neo4j OGM for Laravel
Frequently asked questions about Neoeloquent
- What is vinelab/neoeloquent used for?
- It is a Neo4j OGM for Laravel that lets you define graph nodes and relationships as PHP model classes. You use Eloquent-style query building and eager loading while the data is stored and queried through Neo4j and Cypher. It fits graph-native domains such as relationship-heavy applications, recommendations, dependency mapping, and network analysis, not general relational modeling.
- How do I install NeoEloquent in a Laravel application?
- Install the package with Composer and wire it into Laravel using the package service provider and configuration. You also need Neo4j connectivity configured for the environment where the app runs. Follow the repository README for exact provider registration and config publishing steps, then run a small connection test before modeling graph data.
- Which Laravel, PHP, and Neo4j versions are supported by NeoEloquent?
- The package overview and TPM evaluation do not publish a definitive compatibility matrix, so check the repository composer.json, release notes, and CI configuration for the exact Laravel, PHP, and Neo4j driver constraints. Pin the package version and verify it against your target runtime and Neo4j server before adopting it. Compatibility with newer Laravel upgrades should be part of your regression testing.
- How do I configure a Neo4j connection for NeoEloquent in Laravel?
- Add a Neo4j connection in the package configuration and point it at your Neo4j host, credentials, and selected database. Keep connection details environment-specific so local, CI, staging, and production do not share accidental graph targets. Document selected database names and test connectivity from each environment.
- Can NeoEloquent select a specific Neo4j database per connection?
- Yes, v1.8.2 adds selectable Neo4j database connections. That helps separate environments, tenants, or graph workloads when routing is configured correctly. Treat database selection as configuration that needs validation, because misrouting can send queries to the wrong graph and it does not by itself provide tenant isolation.
- How do relationships and eager loading work in NeoEloquent?
- NeoEloquent models represent graph nodes and relationships using Eloquent-style class definitions. The package supports familiar query building and eager loading so you can traverse relationships without dropping to raw Cypher for every query. Developers still need to understand graph modeling and relationship traversal because graph semantics differ from relational joins.
- Does NeoEloquent behave exactly like standard Laravel Eloquent?
- No. It follows Eloquent conventions where practical, but it is backed by Neo4j and Cypher, so behavior can diverge from relational Eloquent in query semantics, relationships, and edge cases. The v1.8.2 MassAssignmentException fix shows that fillable and guarded behavior should be tested explicitly. Do not assume every relational Eloquent feature maps one-to-one.
- What changed in NeoEloquent v1.8.2?
- v1.8.2 is a minor non-breaking update that adds selectable Neo4j database connections and fixes an incorrect MassAssignmentException class-not-found error when filling non-fillable attributes. The database-selection change is useful for multi-environment or separated graph workloads. The mass-assignment fix reduces a known runtime failure path but does not remove the need for fillable and guarded regression tests.
- How should I test mass assignment with NeoEloquent?
- Create model-level tests that fill fillable attributes and assert they persist, then attempt non-fillable attributes and assert the expected exception or guarded behavior. Cover both direct assignment and mass assignment paths after the v1.8.2 fix. Run these tests on every Laravel and package upgrade because ORM edge cases can regress silently.
- What are the production risks of using NeoEloquent with Neo4j?
- Watch for connection or database misrouting, missing Neo4j indexes and schema, unexpected mass-assignment behavior, and package incompatibility after Laravel upgrades. Scaling depends heavily on Neo4j topology, indexing, query patterns, and connection pooling rather than this release alone. Add observability, rollback procedures, and internal ownership because community package maintenance may not cover every edge case.
Weaver
How can I help you explore Laravel packages today?