Platform Organization Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require digitalstate/platform-organization-bundle
   

   Register it in config/bundles.php:

   return [
       // ...
       DigitalState\Bundle\OrganizationBundle\DsOrganizationBundle::class => ['all' => true],
   ];
   

2. First Use Case: Fixture Loading Extend your data fixtures with organization-aware traits/interfaces. Example: Load business units with BusinessUnitExtensionAwareTrait:

   use Ds\Bundle\OrganizationBundle\Migration\Extension\BusinessUnitExtensionAwareTrait;
   
   class LoadBusinessUnitData extends AbstractFixture implements BusinessUnitExtensionAwareInterface
   {
       use BusinessUnitExtensionAwareTrait;
   
       public function load(ObjectManager $manager)
       {
           $this->loadBusinessUnitsFromYaml($manager, 'path/to/business_units.yml');
       }
   }
   

3. Key Files to Review

   • Migration/Extension/ for available extension traits/interfaces.
   • Resources/config/doctrine/ for entity mappings (if extended).
   • DependencyInjection/ for configuration options.

Implementation Patterns

1. Fixture Loading Workflows

• YAML-Based Fixtures: Use loadBusinessUnitsFromYaml(), loadDepartmentsFromYaml(), etc., to populate organization hierarchies.

  # business_units.yml
  business_units:
      - id: 1
        name: "Marketing"
        parent: null
      - id: 2
        name: "Engineering"
        parent: 1
  

  $this->loadBusinessUnitsFromYaml($manager, 'business_units.yml');
  

• Dynamic Parent-Child Relationships: Leverage parent keys in YAML to auto-link entities.

2. Integration with OroPlatform

• Extend Oro’s Organization Bundle: Override or extend Oro’s BusinessUnit, Department, or User entities by injecting this bundle’s services.

  // config/services.yaml
  DigitalState\Bundle\OrganizationBundle\Service\OrganizationService:
      arguments:
          $oroOrganizationManager: '@oro_organization.manager'
  

• Event Listeners: Subscribe to Oro’s organization events (e.g., oro_organization.business_unit.create) and extend logic.

  // src/EventListener/OrganizationListener.php
  public function onBusinessUnitCreate(OrganizationEvent $event)
  {
      $businessUnit = $event->getBusinessUnit();
      // Custom logic (e.g., audit logs, notifications)
  }
  

3. CLI Commands

• Use the bundle’s commands (if any) for bulk operations:

  php bin/console ds:organization:sync-hierarchy
  

4. API/Controller Integration

• Fetch organization data in APIs:

  use DigitalState\Bundle\OrganizationBundle\Entity\BusinessUnit;
  
  public function getBusinessUnits(BusinessUnitRepository $repo)
  {
      return $repo->findAllWithHierarchy();
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • The bundle extends Oro’s OrganizationBundle. Ensure your use statements and service IDs don’t clash (e.g., BusinessUnit vs. DsBusinessUnit).

2. Fixture Loading Order

   • Fixtures must run in the correct order (e.g., BusinessUnit before Department). Use setOrder() in fixtures:

     class LoadDepartmentsData extends AbstractFixture { setOrder(2); }
     

3. Missing Dependencies

   • Requires oro/organization-bundle. Add it explicitly if not auto-installed:

     composer require oro/organization-bundle
     

4. YAML Schema Validation

   • The bundle expects strict YAML keys (e.g., parent must reference existing IDs). Validate with:

     php bin/console debug:container Ds\Bundle\OrganizationBundle\Validator\BusinessUnitValidator
     

Debugging Tips

• Enable SQL Logging: Add to .env:

  DOCTRINE_ORM_OPTIMIZER_ENABLED=false
  

• Check Fixture Loading: Use dump() in fixtures to verify data:

  $businessUnits = $this->getBusinessUnitExtension()->getBusinessUnits();
  dump($businessUnits);
  

Extension Points

1. Custom Extensions

   • Implement OrganizationExtensionInterface to add new fixture types:

     class CustomExtension implements OrganizationExtensionInterface
     {
         public function loadFromYaml(ObjectManager $manager, string $file, array $data) { ... }
     }
     

   • Register in services.yaml:

     DigitalState\Bundle\OrganizationBundle\Migration\Extension\CustomExtension:
         tags: ['ds_organization.extension']
     

2. Override Entity Mappings

   • Extend base entities (e.g., BusinessUnit) in your bundle’s Resources/config/doctrine/.

3. Configuration

   • Override default settings in config/packages/ds_organization.yaml:

     ds_organization:
         hierarchy_sync:
             enabled: true
             cron: '0 0 * * *'
     

Performance

• Batch Loading: For large datasets, use Doctrine’s flush() in chunks:

  foreach ($businessUnits as $unit) {
      $manager->persist($unit);
      if ($i % 20 === 0) $manager->flush();
  }