Hierarchybundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require cpana/hierarchybundle
   

   Register the bundle in AppKernel.php:

   new CPANA\HierarchyBundle\CPANAHierarchyBundle(),
   

2. Configure Neo4j Connection Add the following to config/packages/cpana_hierarchy.yaml (Symfony 5+) or app/config/config.yml (older versions):

   cpana_hierarchy:
       group_hierarchy_manager_neo4j:
           neo4j_user: 'neo4j'
           neo4j_password: 'your_password'
           def_rel_type_group_to_group: 'PART_OF'
           def_rel_type_user_to_group: 'MEMBER_OF'
           root_group_id: '11111'  # Replace with your root group's Neo4j ID
           manager_role_property: 'manager'
           default_property_group: 'name'
           default_property_user: 'name'
   

3. Import Routes Add to config/routes.yaml (Symfony 5+):

   cpana_hierarchy:
       resource: "@CPANAHierarchyBundle/Resources/config/routing.yml"
   

4. Initialize Database Run the bundle’s command to initialize the hierarchy structure (check bin/console list for available commands):

   php bin/console cpana:hierarchy:init
   

5. First Use Case: Displaying the Hierarchy Use the provided controller to render the hierarchy in a Twig template:

   use CPANA\HierarchyBundle\Controller\HierarchyController;
   
   // In your controller
   $groups = $this->get('cpana.hierarchy.manager.group')->getHierarchy();
   return $this->render('your_template.html.twig', ['groups' => $groups]);
   

Implementation Patterns

Core Workflows

1. Group Management

   • Create/Edit Groups: Use the GroupManager service to add groups to the hierarchy:

     $groupManager = $this->get('cpana.hierarchy.manager.group');
     $groupManager->createGroup('IT', '12345'); // Parent group ID
     

   • Fetch Hierarchy: Retrieve the entire hierarchy as a nested array:

     $hierarchy = $groupManager->getHierarchy();
     

     Example output:

     [
         'id' => '11111',
         'name' => 'Root',
         'children' => [
             ['id' => '22222', 'name' => 'IT', ...],
             ['id' => '33333', 'name' => 'HR', ...],
         ],
     ]
     

2. User Assignment

   • Add Users to Groups: Use the UserManager service to assign users with roles:

     $userManager = $this->get('cpana.hierarchy.manager.user');
     $userManager->addUserToGroup('john_doe', 'employee', '22222'); // User ID, role, group ID
     

   • List Group Members:

     $members = $userManager->getGroupMembers('22222');
     

3. Admin Interface

   • Leverage the built-in admin routes (/admin/hierarchy) for CRUD operations.
   • Extend the admin templates (located in Resources/views/Admin/) to customize the UI.

Integration Tips

• Symfony Forms: Integrate with Symfony forms for group/user creation:

  $builder->add('parentGroup', EntityType::class, [
      'class' => 'CPANA\HierarchyBundle\Entity\Group',
      'property' => 'name',
      'label' => 'Parent Group',
  ]);
  

• Event Listeners: Subscribe to hierarchy events (e.g., HierarchyEvent) to react to changes:

  // In services.yaml
  CPANA\HierarchyBundle\EventListener\YourListener:
      tags:
          - { name: kernel.event_listener, event: cpana.hierarchy.group.created, method: onGroupCreated }
  

• Custom Queries: Use the Neo4jClient service to run custom Cypher queries:

  $neo4j = $this->get('cpana.hierarchy.neo4j.client');
  $result = $neo4j->run('MATCH (g:Group)-[:PART_OF]->(parent) RETURN g, parent');
  

Gotchas and Tips

Pitfalls

1. Neo4j Connection Issues

   • Ensure the Neo4j server is running and accessible from your Symfony environment.
   • Validate credentials in config.yml; hardcoded credentials are insecure—use environment variables:

     neo4j_password: '%env(NEO4J_PASSWORD)%'
     

   • Debug connection errors by checking the neo4jphp logs or enabling Symfony’s profiler.

2. Root Group ID Misconfiguration

   • The root_group_id must match an existing Neo4j node ID. Verify this ID using the Neo4j Browser or cypher-shell:

     MATCH (g) RETURN g LIMIT 1;
     

   • If the root group doesn’t exist, initialize it via the init command or manually in Neo4j.

3. Circular References

   • Avoid creating circular PART_OF relationships (e.g., Group A → Group B → Group A). The bundle doesn’t enforce this, but it can cause infinite loops in traversals. Validate hierarchies in custom queries:

     MATCH path = (g:Group)-[:PART_OF*2..]->(g) RETURN path; // Detect cycles
     

4. Role Property Conflicts

   • The manager_role_property (e.g., manager) must be a unique property on user nodes. Conflicts may arise if users have duplicate properties. Use distinct property names or clean the database first:

     MATCH (u:User) WHERE u.manager IS NOT NULL RETURN u;
     

Debugging

• Enable Query Logging: Configure neo4jphp to log queries in config/packages/cpana_hierarchy.yaml:

  cpana_hierarchy:
      group_hierarchy_manager_neo4j:
          neo4j_log_queries: true
  

  Logs appear in var/log/dev.log.

• Neo4j Browser: Use the Neo4j Browser to inspect the graph structure:

  // Visualize the hierarchy
  MATCH (g:Group)-[:PART_OF*0..5]->(parent:Group)
  RETURN g, parent
  

Extension Points

1. Custom Relationship Types Extend the bundle by adding new relationship types (e.g., SUBORDINATE_OF). Override the GroupManager service:

   # config/services.yaml
   CPANA\HierarchyBundle\Manager\GroupManager:
       arguments:
           $customRelTypes: ['PART_OF', 'SUBORDINATE_OF']
   

2. Custom Properties Add custom properties to groups/users by extending the Group or User entities (located in Entity/). Example:

   namespace App\Entity;
   
   use CPANA\HierarchyBundle\Entity\Group as BaseGroup;
   
   class Group extends BaseGroup
   {
       private $budget;
   }
   

   Update the bundle’s mappings in Resources/config/doctrine/.

3. Override Admin Templates Copy the admin templates from CPANAHierarchyBundle:Admin: to your project’s templates/ directory to customize them without losing updates.

4. Bulk Operations For large hierarchies, use batch processing to avoid timeouts:

   $groupManager->createGroupsBulk([
       ['name' => 'Group1', 'parentId' => '11111'],
       ['name' => 'Group2', 'parentId' => '11111'],
   ]);
   

   (Check if the bundle supports bulk operations; if not, implement a custom service.)

Performance Tips

• Index Neo4j Properties: Create indexes in Neo4j for frequently queried properties (e.g., name):

  CREATE INDEX ON :Group(name);
  CREATE INDEX ON :User(name);
  

• Limit Hierarchy Depth: Restrict traversal depth in queries to avoid performance issues:

  $groupManager->getHierarchy(3); // Limit to 3 levels deep
  

• Cache Hierarchy Data: Cache the hierarchy output in Symfony’s cache system:

  $hierarchy = $this->get('cpana.hierarchy.manager.group')->getHierarchy();
  $this->get('cache.app')->save('hierarchy_data', $hierarchy, 3