Relay Greenlight Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dbp/relay-greenlight-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayGreenlightBundle\RelayGreenlightBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console dbp:relay-greenlight:install
   

   Update config/packages/dbp_relay_greenlight.yaml with your DCC (Digital COVID Certificate) relay server credentials (if available).

3. First Use Case Generate a test permit via CLI:

   php bin/console dbp:relay-greenlight:generate-permit
   

   Verify the output in var/log/relay_greenlight.log.

Implementation Patterns

Core Workflows

1. Permit Generation Use the PermitGenerator service to create permits programmatically:

   $generator = $this->container->get('dbp_relay_greenlight.permit_generator');
   $permit = $generator->generate([
       'subject' => 'Test User',
       'issuer' => 'Test Issuer',
       'valid_from' => now()->subDays(1),
       'valid_until' => now()->addDays(1),
   ]);
   

2. Event-Driven Permits Extend the bundle to trigger permit generation on events (e.g., user registration):

   // In a listener
   public function onUserRegistered(UserRegisteredEvent $event) {
       $generator = $this->container->get('dbp_relay_greenlight.permit_generator');
       $generator->generateForUser($event->getUser());
   }
   

3. Validation Integration Validate permits in controllers/middleware:

   use DigitalBlueprint\RelayGreenlightBundle\Validator\PermitValidator;
   
   $validator = new PermitValidator();
   if (!$validator->isValid($permitData)) {
       throw new \RuntimeException('Invalid permit');
   }
   

Integration Tips

• Symfony Flex: Leverage autowiring for services like PermitGenerator and PermitValidator.
• Doctrine ORM: Use the provided Permit entity to store permits in the database:

  $entityManager->persist($permit);
  $entityManager->flush();
  

• API Endpoints: Expose permit generation via a controller:

  #[Route('/api/permit', methods: ['POST'])]
  public function generatePermit(Request $request, PermitGenerator $generator) {
      $data = json_decode($request->getContent(), true);
      return new JsonResponse($generator->generate($data));
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Infrastructure

   • The bundle relies on the DCC relay server, which is no longer operational (since June 2023). Test locally or mock responses for development.
   • Workaround: Use a local mock server (e.g., WireMock) to simulate DCC relay responses.

2. Configuration Overrides

   • The bundle assumes specific DCC relay endpoints. Override these in config/packages/dbp_relay_greenlight.yaml:

     dbp_relay_greenlight:
         relay_server_url: 'http://localhost:8080' # Mock URL
         timeout: 30
     

3. Logging Dependencies

   • The bundle logs extensively. Ensure monolog is configured in config/packages/monolog.yaml:

     handlers:
         main:
             type: stream
             path: '%kernel.logs_dir%/relay_greenlight.log'
             level: debug
     

Debugging

• Mocking the Relay Server Use PHPUnit to mock the RelayClient service:

  $mockClient = $this->createMock(RelayClient::class);
  $mockClient->method('requestPermit')->willReturn(['mock' => 'response']);
  $this->container->set('dbp_relay_greenlight.relay_client', $mockClient);
  

• Validation Errors Enable debug mode to see detailed validation errors:

  $validator = new PermitValidator();
  $errors = $validator->validate($permitData);
  dd($errors); // Debug validation issues
  

Extension Points

1. Custom Permit Fields Extend the Permit entity:

   namespace App\Entity;
   
   use DigitalBlueprint\RelayGreenlightBundle\Entity\Permit as BasePermit;
   
   class Permit extends BasePermit {
       #[ORM\Column(type: 'string', nullable: true)]
       private ?string $customField = null;
   
       // Add getters/setters
   }
   

2. Event Listeners Subscribe to the PermitGeneratedEvent:

   #[AsEventListener(event: PermitGeneratedEvent::class)]
   public function onPermitGenerated(PermitGeneratedEvent $event) {
       // Send email, log, etc.
   }
   

3. Override Templates Customize the permit template by copying templates/permit.html.twig to templates/dbprelaygreenlight/permit.html.twig.

Performance

• Caching Permits Cache generated permits in Redis or the filesystem to avoid redundant DCC relay calls:

  $cache = $this->container->get('cache.app');
  $permit = $cache->get('permit_' . $userId) ?: $generator->generateForUser($user);