Relay Dispatch Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dbp/relay-dispatch-bundle
   php bin/console doctrine:migrations:migrate --em=dbp_relay_dispatch_bundle
   

2. Configure (config/packages/dbp_relay_dispatch.yaml):

   dbp_relay_dispatch:
       database_url: "mysql://user:pass@localhost/db_name"
       service_url: "https://provider-soap-endpoint"
       sender_profile: "YOUR_PROFILE_ID"
       sender_profile_version: "1.0"
       cert: "%env(DISPATCH_CERT)%"  # Base64-encoded PEM
       cert_password: "%env(DISPATCH_CERT_PASSWORD)%"
   

3. First Use Case: Create a delivery request via CLI (for testing):

   php bin/console dbp:relay:dispatch:test-seed create \
       --request-person-id=1234567890 \
       --recipient-person-id=9876543210 \
       --submit --direct --output-request-xml
   

Implementation Patterns

Core Workflows

1. Request Creation & Submission:

   • Use DispatchRequest entity to model deliveries.
   • Attach documents via DispatchDocument (stored in DB or blob storage).
   • Submit via API (POST /dispatch/requests) or CLI (--submit flag).

2. Recipient Management:

   • Add recipients dynamically:

     $request->addRecipient($recipientEntity);
     

   • Fetch statuses:

     php bin/console dbp:relay:dispatch:status-request ADID_...
     

3. Authorization Integration:

   • Implement ROLE_USER and group-specific roles (e.g., ROLE_GROUP_WRITER) in Symfony’s security voter.
   • Example voter:

     public function supports($attribute, $subject)
     {
         return $attribute instanceof Role && in_array($attribute->getAttribute(), ['ROLE_GROUP_WRITER']);
     }
     

4. SOAP Communication:

   • Bundle handles SOAP calls to the provider. Extend DuaZSpecClient for custom logic if needed.

Integration Tips

• Frontend: Pair with Dispatch Frontend for UI.
• File Storage: Prefer blob storage for large documents (configure blob_base_url, blob_bucket_id, etc.).
• Testing: Use CLI commands to seed test data and validate SOAP responses.

Gotchas and Tips

Pitfalls

1. SOAP Certificate Issues:

   • Ensure cert is base64-decoded in config (see README tips).
   • Test SOAP connectivity with:

     php bin/console dbp:relay:dispatch:status-request ADID_... --output-response-xml
     

2. Authorization Misconfigurations:

   • ROLE_GROUP_WRITER implies all read roles. Verify group assignments in GROUPS attribute.
   • Debug with:

     $this->denyAccessUnlessGranted('ROLE_GROUP_WRITER', $group);
     

3. File Storage Quirks:

   • database storage limits file sizes. Use blob for >1MB files.
   • Clear cached blobs after config changes:

     php bin/console cache:clear
     

Debugging

• API Errors: Check relay:errorId in responses (e.g., dispatch:request-file-missing-request-identifier).
• SOAP Logs: Enable Symfony’s monolog to log SOAP requests/responses.

Extension Points

1. Custom SOAP Clients: Extend DuaZSpecClient to support non-DuaZSpec providers:

   class CustomClient extends DuaZSpecClient {
       public function __construct($serviceUrl, $cert, $certPassword) {
           // Override SOAP options
       }
   }
   

2. Dynamic Group Roles: Use Symfony’s ExpressionLanguage for dynamic role checks:

   ROLE_GROUP_WRITER: 'user.hasRole("ROLE_ADMIN") || user.hasRole("ROLE_" ~ group.getIdentifier())'
   

3. Webhook Handling: Listen for DeliveryStatusChange events to trigger notifications:

   // config/services.yaml
   App\EventListener\StatusChangeListener:
       tags:
           - { name: kernel.event_listener, event: dbp_relay_dispatch.delivery_status_change }