Relay Verity Connector Verapdf Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbp/relay-verity-connector-verapdf-bundle
   

   Ensure DbpRelayVerityConnectorVerapdfBundle is listed before DbpRelayCoreBundle in config/bundles.php.

2. Configuration: Create config/packages/dbp_relay_verity-connector-verapdf.yaml:

   dbp_relay_verity_connector_verapdf:
       url: '%env(VERAPDF_API_URL)%'  # Required
       maxsize: 10485760  # 10MB default (optional)
   

3. First Use Case: Inject the VerapdfClient service into a controller or command:

   use Dbp\Relay\VerityConnectorVerapdfBundle\Client\VerapdfClient;
   
   public function validatePdf(VerapdfClient $client, UploadedFile $file)
   {
       $result = $client->validate($file->getPathname());
       return new JsonResponse($result);
   }
   

Implementation Patterns

Workflows

1. PDF Validation Endpoint:

   • Use the VerapdfClient to validate PDFs in a Symfony controller:

     public function validate(Request $request, VerapdfClient $client)
     {
         $file = $request->file('pdf');
         $result = $client->validate($file->getPathname());
         return $this->json($result);
     }
     

   • Route it via annotations or YAML (e.g., validate_pdf route).

2. Batch Processing:

   • Queue validation jobs using Symfony Messenger:

     use Dbp\Relay\VerityConnectorVerapdfBundle\Message\ValidatePdfMessage;
     
     $bus->dispatch(new ValidatePdfMessage($filePath));
     

   • Handle the message in a worker:

     public function __invoke(ValidatePdfMessage $message, VerapdfClient $client)
     {
         return $client->validate($message->getFilePath());
     }
     

3. Integration with Relay API:

   • Extend the RelayApiController to expose validation as an API endpoint:

     #[Route('/api/validate-pdf', name: 'api_validate_pdf', methods: ['POST'])]
     public function validatePdfApi(Request $request, VerapdfClient $client)
     {
         return $this->handleValidation($request, $client);
     }
     

Tips for Integration

• Environment Variables: Always use %env(VERAPDF_API_URL)% for the API endpoint to avoid hardcoding.
• File Size Handling: Validate file size before sending to VeraPDF:

  if ($file->getSize() > $this->container->getParameter('verapdf.maxsize')) {
      throw new \RuntimeException('File too large');
  }
  

• Error Handling: Wrap VerapdfClient calls in try-catch blocks to handle API failures gracefully:

  try {
      $result = $client->validate($filePath);
  } catch (\Exception $e) {
      return $this->json(['error' => $e->getMessage()], 500);
  }
  

Gotchas and Tips

Pitfalls

1. Bundle Order Dependency:

   • Error: If DbpRelayVerityConnectorVerapdfBundle is listed after DbpRelayCoreBundle in bundles.php, the service may not register.
   • Fix: Ensure the bundle is loaded before the core bundle.

2. Missing Configuration:

   • Error: ParameterNotFoundException if url or maxsize is missing in the YAML config.
   • Fix: Always include both url and maxsize in config/packages/dbp_relay_verity-connector-verapdf.yaml.

3. File Size Limits:

   • Error: VeraPDF may reject files silently if they exceed maxsize.
   • Fix: Validate file size on the client side (e.g., JavaScript) and server side (as shown above).

4. API Rate Limits:

   • Error: VeraPDF may throttle requests if not configured properly.
   • Fix: Implement retry logic with exponential backoff:

     use Symfony\Component\Retry\Retry;
     
     $client = new VerapdfClient($url, $maxsize);
     $retry = Retry::create(3)->withDelay(1000);
     $result = $retry->retry(fn() => $client->validate($filePath));
     

Debugging

• Enable Debug Mode: Set APP_DEBUG=true in .env to log detailed errors from the VerapdfClient.
• Log Responses: Extend the VerapdfClient to log raw API responses:

  public function validate(string $filePath): array
  {
      $response = $this->httpClient->request('POST', $this->url, [
          'body' => file_get_contents($filePath),
      ]);
      $this->logger->debug('VeraPDF Response', ['response' => $response->getContent()]);
      return json_decode($response->getContent(), true);
  }
  

Extension Points

1. Custom Validation Rules:

   • Extend the VerapdfClient to add custom validation logic:

     class CustomVerapdfClient extends VerapdfClient
     {
         public function validateWithCustomRules(string $filePath): array
         {
             $result = parent::validate($filePath);
             if ($result['isValid'] && $this->hasCustomTag($filePath)) {
                 $result['customCheck'] = true;
             }
             return $result;
         }
     }
     

   • Register the custom client as a service:

     services:
         Dbp\Relay\VerityConnectorVerapdfBundle\Client\CustomVerapdfClient:
             arguments:
                 $url: '%env(VERAPDF_API_URL)%'
                 $maxsize: '%verapdf.maxsize%'
             tags: ['verapdf.client']
     

2. Event Listeners:

   • Listen for validation events to trigger side effects (e.g., notifications):

     #[AsEventListener(event: 'verapdf.validation.success')]
     public function onValidationSuccess(ValidationSuccessEvent $event)
     {
         $this->mailer->send(new PdfValidatedEmail($event->getFilePath()));
     }
     

3. Testing:

   • Mock the VerapdfClient in tests:

     $mockClient = $this->createMock(VerapdfClient::class);
     $mockClient->method('validate')->willReturn(['isValid' => true]);
     $this->container->set(VerapdfClient::class, $mockClient);