Relay Verity Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbp/relay-verity-bundle
   

   Ensure DbpRelayVerityBundle is registered before DbpRelayCoreBundle in config/bundles.php.

2. Basic Configuration: Create config/packages/dbp_relay_verity.yaml with a minimal backend (e.g., PDF/A validation):

   dbp_relay_verity:
     backends:
       pdfa:
         validator: 'Dbp\Relay\VerapdfBundle\Service\PDFAValidationAPI'
     profiles:
       default:
         name: 'PDF/A Validation'
         rule: 'pdfa.validity == true'
         checks:
           pdfa:
             backend: 'pdfa'
             config: '{"flavour": "1b"}'
   

3. First Use Case: Trigger validation via the Relay API endpoint (e.g., /api/verity/validate). Example payload:

   {
     "profile": "default",
     "file": "/path/to/document.pdf"
   }
   

Implementation Patterns

Core Workflows

1. Profile-Driven Validation: Define reusable validation profiles in config/packages/dbp_relay_verity.yaml to group checks (e.g., archive, accessibility). Example:

   profiles:
     archive:
       rule: 'pdfa.validity == true && pdfa_b2.validity == true'
       checks:
         pdfa: { backend: 'pdfa', config: '{"flavour": "1b"}' }
         pdfa_b2: { backend: 'pdfa', config: '{"flavour": "b2"}' }
   

2. Backend Integration: Extend validation backends by implementing Dbp\Relay\VerityBundle\Service\ValidationAPIInterface. Register new backends in the config:

   backends:
     custom:
       validator: 'App\Service\CustomValidator'
   

3. API Endpoint Usage:

   • POST to /api/verity/validate with:

     { "profile": "archive", "file": "base64_encoded_file" }
     

   • Response includes validation results per check:

     {
       "success": true,
       "results": {
         "pdfa": { "validity": true, "details": [...] }
       }
     }
     

4. File Handling:

   • Accept files as base64 strings or temporary paths (configured via DbpRelayVerityBundle's file_handler service).
   • For large files, use streaming (extend Dbp\Relay\VerityBundle\Service\FileHandlerInterface).

Integration Tips

• Symfony Messenger: Decouple validation by dispatching Dbp\Relay\VerityBundle\Message\ValidateFile messages.
• Event Listeners: Hook into verity.post_validate events to process results (e.g., log, notify).
• Caching: Cache validation results for immutable files (e.g., using Symfony\Contracts\Cache\CacheInterface).

Gotchas and Tips

Pitfalls

1. Bundle Order:

   • Error: DbpRelayVerityBundle must load before DbpRelayCoreBundle. Misordering causes ServiceNotFoundException.
   • Fix: Verify config/bundles.php order and run php bin/console cache:clear.

2. Backend Service Names:

   • Error: Invalid validator key in backends (e.g., typo in FQCN) throws ServiceNotFoundException.
   • Fix: Use exact class names (e.g., Dbp\Relay\VerapdfBundle\Service\PDFAValidationAPI).

3. File Size Limits:

   • Error: Large files may hit PHP’s post_max_size or memory limits.
   • Fix: Configure upload_max_filesize and use streaming (implement FileHandlerInterface).

4. Rule Syntax:

   • Error: Invalid rule syntax (e.g., pdfa.validity = true without ==) fails silently.
   • Fix: Use strict comparison (==) and validate rules with php bin/console debug:container dbp_relay_verity.rule_parser.

Debugging

• Logs: Enable debug mode (APP_ENV=dev) and check var/log/dev.log for validation errors.
• Dumping Results: Use Symfony’s var dumper in a controller:

  use Symfony\Component\VarDumper\VarDumper;
  VarDumper::dump($validator->validate($file, $profile));
  

Extension Points

1. Custom Validators:

   • Implement ValidationAPIInterface and register in services.yaml:

     services:
       App\Service\CustomValidator:
         tags: ['dbp_relay_verity.backend']
     

2. Profile Dynamic Loading:

   • Override Dbp\Relay\VerityBundle\Loader\ProfileLoaderInterface to load profiles from a database.

3. Result Transformation:

   • Extend Dbp\Relay\VerityBundle\Result\ValidationResult to add custom metadata.

Configuration Quirks

• Backend Dependencies:
  • Some backends (e.g., VerapdfBundle) require additional services (e.g., HTTP clients). Configure them in services.yaml.
• Profile Inheritance:
  • Use extends in profiles to reuse checks:

    profiles:
      extended_archive:
        extends: archive
        checks:
          additional:
            backend: 'custom'