Videolibrary Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require coa/videolibrary-bundle
   

   Enable the bundle in config/bundles.php:

   Coa\VideoLibraryBundle\CoaVideoLibraryBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console coa:videolibrary:install
   

   Update config/packages/coa_videolibrary.yaml with your AWS credentials and S3/MediaConvert settings:

   coa_videolibrary:
       aws:
           region: 'eu-west-1'
           access_key: '%env(AWS_ACCESS_KEY_ID)%'
           secret_key: '%env(AWS_SECRET_ACCESS_KEY)%'
       s3:
           bucket: 'your-video-bucket'
       mediaconvert:
           role_arn: 'arn:aws:iam::123456789012:role/MediaConvertRole'
   

3. First Use Case: Uploading a Video Use the VideoUploader service to upload a file to S3:

   use Coa\VideoLibraryBundle\Service\VideoUploader;
   
   $uploader = $this->get('coa_videolibrary.uploader');
   $result = $uploader->upload(
       $filePath, // Path to local file
       'my-video-title',
       ['tags' => ['demo', 'test']]
   );
   

   The response includes the S3 URL and job ID for MediaConvert processing.

Implementation Patterns

Workflow: Video Processing Pipeline

1. Upload & Metadata Use VideoUploader to upload files and attach metadata (e.g., title, tags, custom fields):

   $uploader->upload($file, 'Lecture 1', [
       'description' => 'Introduction to Laravel',
       'author' => 'John Doe',
       'custom' => ['duration' => 120] // Override auto-detected values
   ]);
   

2. Job Queueing MediaConvert jobs are queued asynchronously. Check status with:

   $jobStatus = $this->get('coa_videolibrary.mediaconvert')->getJobStatus($jobId);
   

3. Output Handling Retrieve processed outputs (e.g., HLS, MP4) via S3:

   $outputs = $this->get('coa_videolibrary.s3')->listObjects(
       $bucket,
       'processed/' . $jobId . '/'
   );
   

4. Entity Management Use the Video entity (auto-generated via Doctrine) to track videos in your database:

   $video = $this->getDoctrine()->getRepository(Video::class)->findOneBy(['s3Key' => $s3Key]);
   

Integration Tips

• Symfony Events Listen for videolibrary.upload.complete or videolibrary.processing.failed to trigger custom logic:

  // config/services.yaml
  Coa\VideoLibraryBundle\EventListener\VideoEventListener:
      tags:
          - { name: kernel.event_listener, event: videolibrary.upload.complete, method: onUploadComplete }
  

• Custom Presets Extend MediaConvert presets in config/packages/coa_videolibrary.yaml:

  coa_videolibrary:
      mediaconvert:
          presets:
              custom_720p:
                  OutputGroupName: '720p Group'
                  Outputs:
                      - ContainerSettings: {Container: 'MP4'}
                        VideoDescription: {CodecSettings: {Codec: 'H_264'}}
  

• Batch Processing Use the VideoBatchProcessor to handle multiple files:

  $processor = $this->get('coa_videolibrary.batch_processor');
  $results = $processor->processBatch($filePaths, 'batch-123');
  

Gotchas and Tips

Pitfalls

1. AWS Credentials

   • Hardcoding credentials in config/ is unsafe. Always use environment variables (%env()).
   • Test credentials with aws s3 ls or the AWS CLI before relying on the bundle.

2. MediaConvert Role Permissions

   • Ensure the IAM role has AmazonS3FullAccess and AWSMediaConvertFullAccess.
   • Debug permission errors with CloudWatch logs for MediaConvert.

3. S3 Bucket Policy

   • The bucket must allow PutObject, GetObject, and DeleteObject for the MediaConvert role.
   • Example policy:

     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Principal": {"AWS": "arn:aws:iam::123456789012:role/MediaConvertRole"},
           "Action": ["s3:*"],
           "Resource": ["arn:aws:s3:::your-bucket", "arn:aws:s3:::your-bucket/*"]
         }
       ]
     }
     

4. Job Timeouts

   • MediaConvert jobs can take hours. Implement a retry mechanism for failed jobs:

     $retry = $this->get('coa_videolibrary.retry_handler');
     $retry->retryJob($jobId, 3); // Retry 3 times
     

Debugging

1. Enable Logging Add to config/packages/monolog.yaml:

   handlers:
       coa_videolibrary:
           type: stream
           path: "%kernel.logs_dir%/coa_videolibrary.log"
           level: debug
   

2. Common Errors

   • "InvalidJobState": The job ID is incorrect or expired. Regenerate it via the AWS Console.
   • S3 Upload Failures: Check bucket CORS settings if using a frontend upload flow.
   • MediaConvert Throttling: Increase the MaxConcurrentJobs in the role policy if hitting limits.

Extension Points

1. Custom Storage Backends Override the S3 adapter by binding a custom service:

   # config/services.yaml
   coa_videolibrary.s3:
       class: App\Service\CustomS3Adapter
       arguments: ['@aws.s3']
   

2. Pre/Post-Processing Hooks Extend the VideoUploader class to add validation or transformations:

   class CustomVideoUploader extends VideoUploader {
       protected function beforeUpload($file, array $metadata) {
           // Add watermark, resize, etc.
       }
   }
   

   Bind it in services.yaml:

   coa_videolibrary.uploader: '@app.custom_video_uploader'
   

3. Database Schema Extend the Video entity to add custom fields:

   // src/Entity/Video.php
   /**
    * @ORM\Column(type="string", nullable=true)
    */
   private $customField;