Neo4J Ogm Bundle Laravel Package

Getting Started

1. Install via Composer: composer require klaussilveira/neo4j-ogm-bundle – note this is a Symfony2 bundle, so you’ll need a Symfony2 project (or adapt the service definitions manually for Laravel).
2. Enable the bundle in AppKernel.php: new Klaussilveira\Neo4jOgmBundle\Neo4jOgmBundle().
3. Configure the connection in config.yml under neo4j_ogm – typically host, port, username, password.
4. Define your first entity using annotations (e.g., @Node, @Property, @Relationship). The bundle wires an EntityManager service you can inject.
5. First use case: inject the entity manager into a controller or service, persist a simple node, and retrieve it by ID. Look first at the bundle’s README.md and the Resources/config/services.xml to see the service IDs and expected configuration keys. The underlying library is hirevoice/neo4jphp-ogm – its documentation is your primary reference for mapping and query methods.

Implementation Patterns

• Entity manager injection: Use Symfony’s DI to inject the neo4j_ogm.entity_manager service into your services or controllers. This mirrors Laravel’s Eloquent facade but requires explicit injection.
• Repository pattern: The OGM supports custom repositories. Define a repository class and annotate your entity with @Repository. Use it for complex Cypher queries while keeping entities clean.
• Annotations for mapping: Properties are mapped via @Property, relationships via @Relationship, and nodes via @Node. This is similar to Doctrine ORM but for graph structures.
• Persist / merge / delete: Standard operations: $em->persist($entity), $em->flush(), $em->find('EntityClass', $id), $em->remove($entity).
• Integration with Symfony services: Because the bundle provides a service, you can inject the entity manager anywhere. For Laravel developers, think of it as a singleton you resolve from the container – but you’ll need to manually bind it if you’re not using Symfony.
• Custom Cypher: Use the underlying Client service for raw Cypher queries when the OGM’s abstraction is too limiting. The bundle may expose a neo4j_ogm.client service.
• Console commands: The bundle may register commands (e.g., schema creation) – check Command/ directory. Run php app/console list to see available neo4j commands.

Gotchas and Tips

• Symfony2 legacy: This bundle targets Symfony2 (and possibly early Symfony3). Modern Symfony (5/6) and Laravel won’t work out of the box – you’ll need to adapt service definitions or use the underlying OGM library directly.
• Connection configuration quirks: The bundle expects specific keys (e.g., transport, host, port). Double-check the bundle’s DependencyInjection/Configuration.php for exact schema.
• Debugging: Use Neo4j Browser to verify data is actually persisted. Enable Symfony’s debug toolbar? Not applicable – instead, log Cypher queries or use the Client’s debug mode if available.
• No transactions: Neo4j OGM doesn’t provide RDBMS-style transactions. Batch operations carefully; use flush() sparingly.
• Mapping limitations: The OGM’s annotation support is basic compared to Doctrine. Complex relationships (e.g., bidirectional) may require manual handling.
• Extension points: Override service definitions in your app’s services.yml to customise the entity manager or client. You can also create a compiler pass to register repositories.
• Performance: The OGM adds overhead. For read-heavy or complex graph traversals, drop to raw Cypher via the client service.
• Laravel adaptation: If you’re using Laravel, you can still use the hirevoice/neo4jphp-ogm library directly. Create a service provider that binds an EntityManager singleton, and replicate the bundle’s configuration manually. The bundle itself is not needed.