Relay Authentic Documents Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer (if available in a public registry or via private setup):

   composer require dbp/relay-authentic-documents-bundle
   

   Register the bundle in config/app.php under providers:

   DigitalBlueprint\RelayAuthenticDocumentsBundle\RelayAuthenticDocumentsBundle::class,
   

2. Configuration Publish the bundle’s config and migrations:

   php artisan vendor:publish --provider="DigitalBlueprint\RelayAuthenticDocumentsBundle\RelayAuthenticDocumentsBundle" --tag="config"
   php artisan migrate
   

   Review config/relay_authentic_documents.php for required API keys, endpoints, or service configurations.

3. First Use Case: Document Upload Use the bundle’s service to authenticate and upload a document via the Relay API:

   use DigitalBlueprint\RelayAuthenticDocumentsBundle\Service\DocumentService;
   
   $documentService = app(DocumentService::class);
   $response = $documentService->uploadDocument(
       $filePath, // Path to local file
       ['metadata' => ['user_id' => 123]] // Optional metadata
   );
   

   Check the documentation for the exact method signatures and expected payloads.

Implementation Patterns

Workflow: Document Authentication Pipeline

1. Pre-Upload Validation Validate documents before submission using the bundle’s validator:

   use DigitalBlueprint\RelayAuthenticDocumentsBundle\Validator\DocumentValidator;
   
   $validator = new DocumentValidator();
   $errors = $validator->validate($filePath, ['type' => 'passport']);
   if ($errors->count() > 0) {
       // Handle validation errors
   }
   

2. Integration with Laravel Storage Store processed documents in Laravel’s filesystem (e.g., S3) while keeping Relay’s metadata:

   $documentService->uploadAndStore(
       $filePath,
       'public_documents',
       ['relay_id' => $response['id']]
   );
   

3. Event-Driven Extensions Listen for document events (e.g., DocumentUploaded) to trigger side effects:

   use DigitalBlueprint\RelayAuthenticDocumentsBundle\Events\DocumentUploaded;
   
   DocumentUploaded::subscribe(function ($event) {
       // Send notification, log, or update a CRM
   });
   

4. API Wrapper Usage Use the bundle’s HTTP client to interact with Relay’s API directly:

   $client = app(\DigitalBlueprint\RelayAuthenticDocumentsBundle\Client\RelayClient::class);
   $documents = $client->listDocuments(['user_id' => 123]);
   

Common Patterns

• Dependency Injection: Prefer injecting DocumentService or RelayClient into controllers/services.
• Configuration Overrides: Extend the bundle’s config via environment variables or custom config files.
• Testing: Mock RelayClient in tests to avoid hitting the real API:

  $this->app->instance(RelayClient::class, Mockery::mock(RelayClient::class));
  

Gotchas and Tips

Pitfalls

1. API Rate Limits The bundle does not handle Relay’s rate limits by default. Implement a retry mechanism with exponential backoff:

   use Symfony\Component\HttpClient\RetryableHttpClient;
   
   $client = new RetryableHttpClient(
       $baseClient,
       [
           'max_retries' => 3,
           'delay' => 100,
           'multiplier' => 2,
           'statuses' => [429],
       ]
   );
   

2. File Size Limits Relay may reject large files. Validate file sizes before upload:

   if ($file->getSize() > 10 * 1024 * 1024) { // 10MB
       throw new \RuntimeException('File too large');
   }
   

3. Metadata Handling Relay’s API may enforce strict metadata schemas. Use the bundle’s DocumentMetadata class to ensure consistency:

   $metadata = new \DigitalBlueprint\RelayAuthenticDocumentsBundle\Model\DocumentMetadata();
   $metadata->setUserId(123)->setType('passport');
   

4. Archived Status The bundle is not production-ready. Expect breaking changes. Fork and extend if critical for your project.

Debugging Tips

• Enable API Logging: Configure the RelayClient to log requests/responses:

  $client->setDebug(true);
  

• Check Relay’s Response Codes: Relay may return non-standard HTTP codes (e.g., 4XX for validation errors). Handle them explicitly:

  try {
      $response = $documentService->uploadDocument($filePath);
  } catch (\DigitalBlueprint\RelayAuthenticDocumentsBundle\Exception\RelayValidationException $e) {
      // Handle validation errors
  }
  

Extension Points

1. Custom Document Types Extend the DocumentType enum or create a custom validator for niche document types.

2. Webhook Integration Implement a webhook listener for Relay’s document events (e.g., document.processed):

   use DigitalBlueprint\RelayAuthenticDocumentsBundle\Events\RelayWebhookReceived;
   
   RelayWebhookReceived::listen(function ($event) {
       // Process webhook payload
   });
   

3. Storage Adapters Override the default storage handler to support custom backends (e.g., Google Cloud Storage):

   $documentService->setStorageAdapter(new CustomStorageAdapter());
   

4. Testing Relay Mocks Use the bundle’s RelayClientMock for unit tests:

   $mock = new RelayClientMock();
   $mock->shouldReceive('upload')->once()->andReturn(['id' => '123']);
   

```markdown
## Additional Notes for Laravel Developers
- **Service Container Binding**: Bind custom implementations of `RelayClientInterface` for testing or feature extensions.
- **Queue Jobs**: Offload document processing to Laravel queues to avoid timeouts:
  ```php
  Dispatch(new ProcessDocumentJob($filePath, $metadata));

• Localization: The bundle may lack translations. Extend the translations config or use Laravel’s json locale files.
• Security: Sanitize all Relay API responses to prevent XSS if rendering document metadata in views.