Relay Blob Connector Campusonline Dms Bundle Laravel Package

Getting Started

Minimal Setup Steps

1. Install the Bundle

   composer require dbp/relay-blob-connector-campusonline-dms-bundle
   

   Ensure dbp/relay-blob-bundle is also installed as a dependency.

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayBlobBundle\RelayBlobBundle::class => ['all' => true],
       DigitalBlueprint\RelayBlobConnectorCampusonlineDmsBundle\RelayBlobConnectorCampusonlineDmsBundle::class => ['all' => true],
   ];
   

3. Configure the Connector Add to config/packages/relay_blob.yaml:

   relay_blob:
       connectors:
           campusonline_dms:
               class: DigitalBlueprint\RelayBlobConnectorCampusonlineDmsBundle\Connector\CampusonlineDmsConnector
               options:
                   api_url: '%env(CAMPUSONLINE_API_URL)%'
                   api_key: '%env(CAMPUSONLINE_API_KEY)%'
                   endpoint: 'object-store' # or custom endpoint if needed
   

4. First Use Case: Upload a File Inject the blob service and use the configured connector:

   use DigitalBlueprint\RelayBlobBundle\Service\BlobService;
   
   public function uploadFile(BlobService $blobService, UploadedFile $file)
   {
       $blob = $blobService->store($file, 'campusonline_dms');
       return $blob->getUrl(); // Returns CAMPUSonline Object Store URL
   }
   

Implementation Patterns

Core Workflows

1. File Upload/Download

   • Use BlobService to delegate operations to the CAMPUSonline connector.
   • Example:

     // Upload
     $blob = $blobService->store($file, 'campusonline_dms');
     
     // Download
     $fileContent = $blobService->retrieve($blob->getId());
     

2. Metadata Handling

   • Pass metadata via the store() method:

     $blob = $blobService->store($file, 'campusonline_dms', [
         'metadata' => [
             'author' => 'user@example.com',
             'course_id' => 123,
         ],
     ]);
     

3. Error Handling

   • Wrap calls in try-catch to handle CAMPUSonline API errors:

     try {
         $blob = $blobService->store($file, 'campusonline_dms');
     } catch (\DigitalBlueprint\RelayBlobConnectorCampusonlineDmsBundle\Exception\ApiException $e) {
         // Log or notify (e.g., CAMPUSonline API rate limit)
     }
     

4. Integration with Laravel Filesystem

   • Use the Storage facade with the relay-blob disk:

     use Illuminate\Support\Facades\Storage;
     
     Storage::disk('relay_blob')->put('file.pdf', $file);
     

Advanced Patterns

1. Custom Endpoints Override the default object-store endpoint in configuration:

   options:
       endpoint: 'custom-object-store-endpoint'
   

2. Event Listeners Subscribe to blob.stored or blob.retrieved events for post-processing:

   // src/EventListener/BlobListener.php
   public function onBlobStored(BlobStoredEvent $event)
   {
       if ($event->getConnectorName() === 'campusonline_dms') {
           // Log or trigger additional actions
       }
   }
   

3. Testing Mock the connector in tests:

   $this->mock(DigitalBlueprint\RelayBlobConnectorCampusonlineDmsBundle\Connector\CampusonlineDmsConnector::class)
        ->shouldReceive('upload')
        ->andReturn(new Blob('test-id', 'campusonline_dms'));
   

Gotchas and Tips

Common Pitfalls

1. API Key/URL Misconfiguration

   • Ensure CAMPUSONLINE_API_URL and CAMPUSONLINE_API_KEY are set in .env.
   • Validate the API endpoint exists (e.g., https://your-campusonline-instance.com/api/object-store).

2. Rate Limiting

   • CAMPUSonline may throttle requests. Implement exponential backoff in custom connectors if needed.

3. File Size Limits

   • Check CAMPUSonline’s max file size (e.g., 50MB). Stream large files to avoid memory issues:

     $blobService->store($file, 'campusonline_dms', ['stream' => true]);
     

4. Connector Naming Collisions

   • Avoid naming conflicts with other relay-blob connectors. Use unique names like campusonline_dms_v2.

Debugging Tips

1. Enable API Logging Add to config/packages/relay_blob.yaml:

   debug: true
   

   Logs will appear in var/log/dev.log.

2. Inspect Raw API Responses Override the connector to dump responses:

   // src/Connector/CustomCampusonlineDmsConnector.php
   public function upload($file, array $options)
   {
       $response = $this->client->upload(...);
       \Log::debug('CAMPUSonline API Response:', ['response' => $response]);
       return $response;
   }
   

3. Validate Metadata CAMPUSonline may reject certain metadata keys. Test with minimal metadata first:

   $blobService->store($file, 'campusonline_dms', ['metadata' => ['key' => 'value']]);
   

Extension Points

1. Custom Headers Extend the connector to add headers:

   // src/Connector/CustomCampusonlineDmsConnector.php
   protected function getHeaders(): array
   {
       return array_merge(parent::getHeaders(), [
           'X-Custom-Header' => 'value',
       ]);
   }
   

2. Pre/Post-Processing Use Symfony events to modify blobs before/after operations:

   # config/services.yaml
   services:
       App\EventSubscriber\BlobSubscriber:
           tags:
               - { name: kernel.event_subscriber }
   

3. Fallback Connectors Implement a fallback chain if CAMPUSonline fails:

   $blobService->store($file, ['campusonline_dms', 's3_fallback']);