Relay Esign Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require dbp/relay-esign-bundle
   php artisan vendor:publish --provider="DigitalBlueprint\RelayEsignBundle\RelayEsignBundle" --tag="config"
   

2. Configure Providers Edit config/relay_esign.php to define your PDF-AS and MOA-SSP server endpoints under providers. Example:

   'providers' => [
       'pdfas' => [
           'url' => 'https://pdfas.example.com',
           'username' => env('PDFAS_USERNAME'),
           'password' => env('PDFAS_PASSWORD'),
       ],
       'moa_ssp' => [
           'url' => 'https://moa-ssp.example.com',
           'client_id' => env('MOA_CLIENT_ID'),
           'client_secret' => env('MOA_CLIENT_SECRET'),
       ],
   ],
   

3. First Use Case: Sign a PDF

   use DigitalBlueprint\RelayEsignBundle\Service\SignatureService;
   
   $signatureService = app(SignatureService::class);
   $result = $signatureService->signPdf(
       file_get_contents('path/to/document.pdf'),
       'recipient@example.com',
       'pdfas' // Provider key
   );
   file_put_contents('signed.pdf', $result['pdf']);
   

4. Verify a Signature

   $isValid = $signatureService->verifyPdfSignature('signed.pdf');
   

Where to Look First

• Configuration Docs for provider setup.
• API Docs for detailed endpoint usage.
• Service Container: The SignatureService class is the primary entry point for most operations.

Implementation Patterns

Core Workflows

1. PDF Signing Workflow

   • Preparation: Convert document to base64 or stream directly.
   • Execution:

     $signatureService->signPdf(
         $documentBase64,
         $recipientEmail,
         $providerKey,
         ['reason' => 'Contract approval', 'location' => 'Vienna']
     );
     

   • Post-processing: Handle the returned PDF and metadata (e.g., save to storage, log signatures).

2. Batch Processing Use Laravel queues to offload signing tasks:

   SignPdfJob::dispatch($documentPath, $recipient, $providerKey)
       ->onQueue('esign');
   

3. Signature Verification

   $verification = $signatureService->verifyPdfSignature($filePath);
   // $verification includes: isValid, signer, timestamp, etc.
   

Integration Tips

• Laravel Storage: Integrate with Laravel’s filesystem for document storage:

  use Illuminate\Support\Facades\Storage;
  
  $document = Storage::disk('s3')->get('contracts/agreement.pdf');
  $signed = $signatureService->signPdf($document, 'user@example.com', 'pdfas');
  Storage::disk('s3')->put('contracts/signed_agreement.pdf', $signed['pdf']);
  

• Event Dispatching: Trigger events for pre/post-signing actions:

  event(new PdfSigningStarted($documentId, $recipient));
  $result = $signatureService->signPdf(...);
  event(new PdfSigned($result, $documentId));
  

• Fallback Providers: Configure multiple providers and implement a fallback strategy:

  try {
      return $signatureService->signPdf($doc, $email, 'pdfas');
  } catch (ProviderException $e) {
      return $signatureService->signPdf($doc, $email, 'moa_ssp');
  }
  

• Frontend Integration: Use the ESign Frontend App for UI components or expose a Laravel API endpoint:

  Route::post('/api/sign', [SignatureController::class, 'sign']);
  

Common Use Cases

Gotchas and Tips

Pitfalls

1. Provider-Specific Errors

   • PDF-AS and MOA-SSP may return different error formats. Always wrap calls in try-catch:

     try {
         $result = $signatureService->signPdf(...);
     } catch (PdfAsException $e) {
         Log::error('PDF-AS Error: ' . $e->getMessage());
         // Handle or rethrow
     }
     

2. PDF Size Limits

   • Some providers enforce size limits (e.g., 50MB). Validate files before submission:

     if ($request->file('document')->getSize() > 50 * 1024 * 1024) {
         throw new \Exception('File too large');
     }
     

3. Caching Configuration

   • The bundle may cache provider configurations. Clear cache after changes:

     php artisan config:clear
     

4. Timeouts

   • Long-running signing processes may hit PHP timeouts. Increase max_execution_time or use queues.

5. Character Encoding

   • Ensure recipient emails and signing reasons are UTF-8 encoded to avoid issues with special characters.

Debugging

• Enable Debug Mode: Set debug: true in config/relay_esign.php for verbose logs.
• Check Provider Responses: Log raw responses from providers to diagnose issues:

  $signatureService->setLogger(app(\Monolog\Logger::class)->withName('esign_debug'));
  

• Test with Minimal Payloads: Start with small PDFs (e.g., 1 page) to isolate issues.

Configuration Quirks

1. Environment Variables

   • Always use .env for sensitive data (e.g., PDFAS_USERNAME). The bundle does not auto-load these by default.

2. Default Provider

   • If no provider is specified, the bundle uses the first configured provider. Explicitly pass the key to avoid ambiguity.

3. SSL Verification

   • Disable SSL verification only for testing (not production):

     'providers' => [
         'pdfas' => [
             'verify_ssl' => env('PDFAS_VERIFY_SSL', true),
         ],
     ],
     

Extension Points

1. Custom Providers Extend the DigitalBlueprint\RelayEsignBundle\Provider\AbstractProvider class to support additional signing services.

2. Signature Metadata Override the SignatureService to add custom metadata to signatures:

   $signatureService->extendMetadata(function ($metadata) {
       $metadata['custom_field'] = auth()->id();
       return $metadata;
   });
   

3. Webhook Integration Implement a WebhookListener to handle provider callbacks (e.g., for signing completion events).

4. Testing Use the bundle’s test utilities to mock providers:

   $mockProvider = new MockPdfAsProvider();
   $this->app->instance('pdfas_provider', $mockProvider);