Platform Security Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require digitalstate/platform-security-bundle
   

   Add to config/bundles.php:

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

2. First Use Case: Load ACL data fixtures via migrations. Create a migration class extending AbstractFixture and implementing AclExtensionAwareInterface:

   use Ds\Bundle\UserBundle\Migration\Extension\AclExtensionAwareTrait;
   
   class LoadAclData extends AbstractFixture implements AclExtensionAwareInterface
   {
       use AclExtensionAwareTrait;
   
       public function load(ObjectManager $manager)
       {
           $this->loadAclDataFromYaml(__DIR__.'/../Resources/data/acl.yml');
       }
   }
   

3. Key Files:

   • Migration/Extension/AclExtension.php (core ACL logic)
   • Resources/config/services.xml (bundle services)
   • Example YAML fixtures in Resources/data/acl.yml

Implementation Patterns

Workflows

1. ACL Fixture Loading:

   • Use loadAclDataFromYaml() in migrations to load YAML-based ACL rules.
   • Example YAML structure:

     resources:
         entity_name:
             - { permission: 'VIEW', role: 'ROLE_USER' }
             - { permission: 'EDIT', role: 'ROLE_ADMIN' }
     

2. Integration with OroSecurityBundle:

   • Extends Oro’s ACL system; leverage existing Oro roles (ROLE_USER, ROLE_ADMIN) or define custom ones.
   • Use AclExtensionAwareTrait to access ACL helpers in migrations.

3. Custom ACL Logic:

   • Override AclExtension to add custom rule validation or transformations.
   • Example:

     $this->aclExtension->setCustomRuleTransformer(function ($rule) {
         $rule['permission'] = strtoupper($rule['permission']);
         return $rule;
     });
     

4. Dependency Injection:

   • Inject AclExtension directly into services:

     use Ds\Bundle\UserBundle\Migration\Extension\AclExtension;
     
     class MyService {
         public function __construct(private AclExtension $aclExtension) {}
     }
     

Integration Tips

• Symfony Migrations: Use the bundle’s extension in doctrine:migrations:load commands.
• Custom Roles: Define roles in security.yaml and reference them in YAML fixtures.
• Testing: Mock AclExtension in unit tests to isolate ACL logic:

  $this->aclExtension = $this->createMock(AclExtension::class);
  $this->aclExtension->method('loadAclDataFromYaml')->willReturn(true);
  

Gotchas and Tips

Pitfalls

1. YAML Parsing Errors:

   • Ensure YAML fixtures follow the expected structure (e.g., resources.entity.permission.role).
   • Debug with var_dump($this->aclExtension->getAclDataFromYaml(file)).

2. ACL Caching:

   • OroSecurityBundle caches ACL rules. Clear cache after modifying fixtures:

     php bin/console cache:clear
     

3. Namespace Conflicts:

   • The bundle assumes Ds\Bundle\UserBundle namespace. If using a custom bundle, override the service definition:

     # config/services.yaml
     Ds\Bundle\UserBundle\Migration\Extension\AclExtension:
         alias: 'your_bundle.acl_extension'
     

4. Migration Order:

   • ACL fixtures must run after entity migrations (e.g., LoadUserData before LoadAclData).

Debugging

• Enable ACL Debugging: Add to config/packages/security.yaml:

  oro_security:
      acl:
          debug: true
  

  Logs ACL operations to var/log/dev.log.

• Check Loaded Rules: Dump ACL rules in a controller:

  $aclHelper = $this->get('oro_security.acl_helper');
  dump($aclHelper->getAclProvider()->getResources());
  

Extension Points

1. Custom ACL Providers: Extend Oro\Bundle\SecurityBundle\Acl\Domain\ObjectIdentityProvider to support custom entities.

2. Post-Load Hooks: Override AclExtension::postLoadAclData() to run logic after fixture loading:

   public function postLoadAclData(array $data)
   {
       // Custom logic (e.g., log loaded rules)
   }
   

3. YAML Schema Validation: Add validation to AclExtension::validateAclData() to enforce custom rules:

   public function validateAclData(array $data): bool
   {
       if (!isset($data['resources'])) {
           throw new \InvalidArgumentException('ACL data must include "resources" key.');
       }
       return true;
   }
   

4. Event Listeners: Listen for oro_security.acl_rule.load events to modify rules dynamically:

   $eventDispatcher->addListener('oro_security.acl_rule.load', function ($event) {
       $event->setRule(['permission' => 'CUSTOM_' . $event->getRule()['permission']]);
   });