Videolibraryms Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require coa/videolibraryms-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Coa\VideoLibraryMsBundle\CoaVideoLibraryMsBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console coa:videolibraryms:install
   

   Update config/packages/coa_videolibraryms.yaml with your:

   • AWS S3 credentials
   • MediaConvert roles/queue names
   • Message broker (RabbitMQ/SQS) settings

3. First Use Case: Upload a Video

   use Coa\VideoLibraryMsBundle\Service\VideoService;
   
   $videoService = $container->get(VideoService::class);
   $result = $videoService->uploadVideo(
       'path/to/local/video.mp4',
       'my-video-title',
       ['tags' => ['demo', 'test']]
   );
   

   • Returns a Video entity with S3 metadata and job IDs for processing.

Implementation Patterns

Core Workflows

1. Video Processing Pipeline

   graph TD
     A[Upload] --> B[S3 Storage]
     B --> C[MediaConvert Job]
     C --> D[Transcoding]
     D --> E[Notification via Broker]
   

   • Trigger Processing: Use VideoService::triggerProcessing($videoId) to kick off MediaConvert.
   • Polling Results: Implement a MediaConvertListener to handle job completion events from the broker.

2. Message Broker Integration

   • Publish Events:

     $this->get('coa_videolibraryms.message_producer')
         ->publish('video.processing.started', ['video_id' => $videoId]);
     

   • Consume Events (e.g., in a worker):

     $consumer = new MediaConvertJobConsumer($this->get('coa_videolibraryms.message_consumer'));
     $consumer->consume();
     

3. Thumbnails and Metadata

   • Generate thumbnails on-the-fly:

     $thumbnailUrl = $videoService->generateThumbnail($videoId, 30); // 30s timestamp
     

   • Update metadata dynamically:

     $videoService->updateMetadata($videoId, ['description' => 'Updated desc']);
     

Integration Tips

• Symfony Events: Bind to coa_videolibraryms.video.uploaded or coa_videolibraryms.video.processed for custom logic.
• API Layer: Expose a VideoController with endpoints like:

  #[Route('/videos/{id}/status', name: 'video_status')]
  public function getStatus(VideoService $videoService, int $id): JsonResponse
  {
      return new JsonResponse($videoService->getVideoStatus($id));
  }
  

• Batch Processing: Use the VideoBatchService for bulk uploads/operations:

  $batchService->processBatch([
      ['file' => 'video1.mp4', 'title' => 'Batch Video 1'],
      ['file' => 'video2.mp4', 'title' => 'Batch Video 2'],
  ]);
  

Gotchas and Tips

Pitfalls

1. AWS Credentials

   • Gotcha: Hardcoded credentials in config override local .env. Always use environment variables:

     # config/packages/coa_videolibraryms.yaml
     aws:
         credentials:
             key: '%env(AWS_ACCESS_KEY_ID)%'
             secret: '%env(AWS_SECRET_ACCESS_KEY)%'
     

   • Tip: Use IAM roles for production deployments to avoid credential leaks.

2. MediaConvert Job Failures

   • Gotcha: MediaConvert jobs may fail silently. Implement a MediaConvertJobRetryListener to handle retries:

     $listener = new MediaConvertJobRetryListener(
         $this->get('coa_videolibraryms.media_convert_client'),
         $this->get('coa_videolibraryms.message_producer')
     );
     

   • Tip: Log job errors to a dedicated table for manual review:

     $videoService->logMediaConvertError($jobId, $errorMessage);
     

3. Broker Message Timeouts

   • Gotcha: Long-running MediaConvert jobs may cause broker timeouts. Increase the message_ttl in config:

     broker:
         message_ttl: 3600000 # 1 hour in ms
     

4. S3 Storage Classes

   • Gotcha: Videos default to STANDARD storage class, which is costly for long-term storage. Override in config:

     s3:
         storage_class: 'GLACIER_IR'
     

Debugging

• Enable Verbose Logging:

  php bin/console debug:config coa_videolibraryms
  

  Set debug: true in config to log AWS/MediaConvert API calls.

• Test Locally with Mocks: Use the Coa\VideoLibraryMsBundle\Tests\Mock\* classes to mock AWS services during development.

Extension Points

1. Custom Video Fields Extend the Video entity by overriding the VideoRepository:

   class CustomVideoRepository extends VideoRepository
   {
       public function addCustomField(Video $video, string $field, $value): void
       {
           // Custom logic
       }
   }
   

   Register the service in services.yaml:

   Coa\VideoLibraryMsBundle\Repository\VideoRepository:
       class: App\Repository\CustomVideoRepository
   

2. Pre/Post Processing Hooks Implement Coa\VideoLibraryMsBundle\Event\VideoEventSubscriber:

   class CustomVideoSubscriber implements VideoEventSubscriber
   {
       public function onVideoUploaded(VideoUploadedEvent $event): void
       {
           // Add watermark, etc.
       }
   }
   

   Register the subscriber in services.yaml:

   services:
       App\Event\CustomVideoSubscriber:
           tags: ['coa_videolibraryms.event_subscriber']
   

3. Custom MediaConvert Presets Define presets in config/packages/coa_videolibraryms.yaml:

   media_convert:
       presets:
           hd:
               video_description: 'HD Video'
               container: 'mp4'
               codec: 'h264'
   

   Use them in the service:

   $videoService->uploadVideo(..., ['preset' => 'hd']);