Assertion Voter Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require appsco/assertion-voter-bundle
   

2. Register the Bundle in AppKernel.php:

   new Appsco\AssertionVoterBundle\AppscoAssertionVoterBundle(),
   

3. Configure in app/config/config.yml:

   appsco_assertion_voter:
       voter_record_provider: appsco.assertion.voter_record_provider.orm
       voter_factory: appsco.assertion.voter_factory.simple
   

First Use Case: Resolving Roles from Assertions

1. Create a VoterRecord Entity (if using Doctrine ORM):

   // src/Acme/YourBundle/Entity/VoterRecord.php
   namespace Acme\YourBundle\Entity;
   use Appsco\AssertionVoterBundle\Entity\VoterRecord as BaseVoterRecord;
   use Doctrine\ORM\Mapping as ORM;
   
   /**
    * @ORM\Entity
    */
   class VoterRecord extends BaseVoterRecord { ... }
   

2. Configure the VoterRecord Class in config.yml:

   appsco_assertion_voter:
       voter_record_class: Acme\YourBundle\Entity\VoterRecord
   

3. Resolve Roles in a Controller:

   public function fooAction()
   {
       $info = $this->get('your_info_provider')->getInfo();
       $roles = $this->get('appsco.assertion.role_resolver')->resolve($info);
       return $this->render('template.html.twig', ['roles' => $roles]);
   }
   

Implementation Patterns

Core Workflow: Assertion-Based Role Resolution

1. Fetch Assertion Data: Use a custom service to gather assertion data (e.g., from an external API, database, or session).

   $info = $this->get('your.assertion_data_service')->getAssertions();
   

2. Resolve Roles: Pass the assertion data to the role_resolver service.

   $roles = $this->get('appsco.assertion.role_resolver')->resolve($info);
   

3. Use Roles in Security: Integrate resolved roles with Symfony’s security system (e.g., via voters or access control).

Integration with Doctrine ORM

1. Define VoterRecords: Extend BaseVoterRecord and map it to your database schema.

   /**
    * @ORM\Column(type="string")
    */
   private $issuer;
   

2. Seed VoterRecords: Populate the VoterRecord table with issuer/attribute/value/role mappings. Example:

   | issuer   | attribute | value  | role          |
   |----------|-----------|--------|---------------|
   | "acme"   | "status"  | "active" | ROLE_ACTIVE   |
   

Custom Decision Makers

1. Create a Decision Maker Service: Implement BWC\Component\AssertionVoter\DecisionMakerInterface and tag it.

   # services.yml
   my.custom_decision_maker:
       class: My\Bundle\Service\CustomDecisionMaker
       tags:
           - { name: appsco.assertion.decision_maker, alias: custom }
   

2. Use in Role Resolution:

   $roles = $this->get('appsco.assertion.role_resolver')->resolve($info, 'custom');
   

Persistence Layer Flexibility

• Doctrine DBAL: Configure table/column names in config.yml:

  appsco_assertion_voter:
      voter_record_provider: appsco.assertion.voter_record_provider.dbal
  

  Customize columns:

  parameters:
      appsco.assertion.voter_record_provider.dbal.table_name: custom_voter_records
      appsco.assertion.voter_record_provider.dbal.role_column: user_role
  

• Custom Providers: Implement VoterRecordProviderInterface for non-Doctrine setups (e.g., MongoDB, Redis).

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.1 Dependency: The bundle requires Symfony 2.1, which may cause compatibility issues with modern Laravel/Lumen (though this is a Symfony bundle; clarify if Laravel is the target framework—adjust accordingly). Workaround: Use in a Symfony 2.1+ project or fork/modernize the bundle.

2. Missing VoterRecord Configuration: Forgetting to set voter_record_class (for ORM) or table_name (for DBAL) will throw ServiceNotFoundException. Fix: Always validate config.yml after setup.

3. Role Resolution Edge Cases:

   • Empty assertion data ($info) returns no roles. Handle gracefully:

     $roles = $this->get('appsco.assertion.role_resolver')->resolve($info ?? []);
     

   • Circular dependencies in decision makers may cause infinite loops. Test thoroughly.

4. Database Schema Mismatches: Ensure VoterRecord columns (issuer, attribute, value, role) match your provider’s expectations. DBAL defaults to VoterRecord table; override if needed.

Debugging Tips

1. Log Resolved Roles: Add a debug listener to log roles before security checks:

   $this->get('logger')->debug('Resolved roles:', ['roles' => $roles]);
   

2. Inspect VoterRecords: Query your VoterRecord table directly to verify mappings:

   SELECT * FROM voter_record WHERE issuer = 'acme';
   

3. Decision Maker Debugging: Implement DecisionMakerInterface::makeDecision() with debug logs:

   public function makeDecision($info, $context) {
       $this->logger->debug('Decision context:', $context);
       return $this->evaluate($info);
   }
   

Extension Points

1. Custom Voter Factories: Extend appsco.assertion.voter_factory.simple for complex role logic:

   services:
       custom.voter_factory:
           class: My\Bundle\Service\CustomVoterFactory
           arguments: ['@service_container']
   

   Update config.yml:

   appsco_assertion_voter:
       voter_factory: custom.voter_factory
   

2. Dynamic Role Resolution: Use event listeners to modify roles at runtime (e.g., add ROLE_TEMPORARY based on time):

   $roleResolver->addPostResolver(function($roles) {
       return array_merge($roles, ['ROLE_TEMPORARY']);
   });
   

3. Caching: Cache resolved roles to avoid repeated database lookups:

   $cache = $this->get('cache');
   $cachedRoles = $cache->get('assertion_roles_' . md5(serialize($info)));
   if (!$cachedRoles) {
       $cachedRoles = $this->get('appsco.assertion.role_resolver')->resolve($info);
       $cache->set('assertion_roles_' . md5(serialize($info)), $cachedRoles, 3600);
   }