Vimeo Api Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require vimeo/vimeo-api
   

   Add to composer.json if using Laravel's config/app.php:

   "require": {
       "vimeo/vimeo-api": "^4.0"
   }
   

2. Configuration: Store credentials in Laravel's .env:

   VIMEO_CLIENT_ID=your_client_id
   VIMEO_CLIENT_SECRET=your_client_secret
   VIMEO_ACCESS_TOKEN=your_access_token  # Optional (for authenticated requests)
   

3. Service Provider: Register in config/app.php:

   'providers' => [
       // ...
       Vimeo\VimeoServiceProvider::class,
   ],
   

4. First Use Case: Fetch your account details in a controller:

   use Vimeo\Vimeo;
   
   public function getAccountDetails()
   {
       $vimeo = new Vimeo(
           config('services.vimeo.client_id'),
           config('services.vimeo.client_secret'),
           config('services.vimeo.access_token')
       );
   
       $me = $vimeo->request('/me')->body;
       return response()->json($me);
   }
   

Implementation Patterns

Core Workflows

1. Authenticated Requests: Use the access token for user-specific actions:

   $vimeo = new Vimeo($clientId, $clientSecret, $accessToken);
   $videos = $vimeo->request('/me/videos')->body;
   

2. Video Uploads:

   • Direct Upload (for small files):

     $upload = $vimeo->upload([
         'uri' => 'https://example.com/video.mp4',
         'name' => 'My Video',
         'description' => 'A test video'
     ]);
     

   • TUS Protocol (for large files):

     $upload = $vimeo->performTusUpload(
         '/path/to/video.mp4',
         ['name' => 'Large Video']
     );
     

3. Pagination: Handle paginated responses:

   $response = $vimeo->request('/videos', ['page' => 1, 'per_page' => 10]);
   $totalPages = $response->total_pages;
   

4. Webhooks: Validate Vimeo webhook signatures:

   $vimeo = new Vimeo($clientId, $clientSecret);
   $isValid = $vimeo->validateWebhookSignature(
       $_SERVER['HTTP_VIMEO_SIGNATURE'],
       file_get_contents('php://input')
   );
   

Laravel-Specific Patterns

1. Service Container Binding: Bind the client in AppServiceProvider:

   $this->app->singleton(Vimeo::class, function ($app) {
       return new Vimeo(
           config('services.vimeo.client_id'),
           config('services.vimeo.client_secret'),
           config('services.vimeo.access_token')
       );
   });
   

2. API Facade: Create a facade for cleaner syntax:

   // app/Facades/Vimeo.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class Vimeo extends Facade {
       protected static function getFacadeAccessor() {
           return 'vimeo';
       }
   }
   

   Register in AppServiceProvider:

   Facade::bind('Vimeo', Vimeo::class);
   

3. Jobs for Async Operations: Queue video uploads:

   // app/Jobs/UploadVimeoVideo.php
   use Vimeo\Vimeo;
   
   class UploadVimeoVideo implements ShouldQueue {
       protected $vimeo;
       protected $filePath;
       protected $metadata;
   
       public function __construct(Vimeo $vimeo, $filePath, $metadata) {
           $this->vimeo = $vimeo;
           $this->filePath = $filePath;
           $this->metadata = $metadata;
       }
   
       public function handle() {
           $this->vimeo->performTusUpload($this->filePath, $this->metadata);
       }
   }
   

4. Middleware for Auth: Protect routes requiring Vimeo auth:

   // app/Http/Middleware/VimeoAuth.php
   public function handle($request, Closure $next) {
       if (!$request->user()->token) {
           return redirect()->route('vimeo.auth');
       }
       return $next($request);
   }
   

Gotchas and Tips

Common Pitfalls

1. Dot Notation vs. Associative Arrays:

   • Vimeo API docs use dot notation (e.g., privacy.view), but the PHP library requires nested arrays:

     // Correct:
     $params = ['privacy' => ['view' => 'disable']];
     // Incorrect (will fail):
     $params = ['privacy.view' => 'disable'];
     

2. TUS Upload Quirks:

   • Large file uploads (>500MB) must use the TUS protocol. Direct uploads fail silently for large files.
   • Ensure your server supports PATCH requests for TUS uploads. Configure your web server (e.g., Nginx) to handle them:

     location /tus/ {
         client_max_body_size 0;
         tus_upload_path /path/to/uploads;
         tus_upload_resume;
         tus_upload_methods "PATCH";
     }
     

   • Default chunk size for TUS is 5MB. Override in the performTusUpload call:

     $upload = $vimeo->performTusUpload(
         $filePath,
         $metadata,
         10 * 1024 * 1024 // 10MB chunks
     );
     

3. Rate Limiting:

   • Vimeo enforces rate limits (e.g., 100 requests/minute for unauthenticated calls). Handle 429 Too Many Requests responses:

     try {
         $response = $vimeo->request('/videos');
     } catch (\Vimeo\Exception\ApiException $e) {
         if ($e->getCode() === 429) {
             sleep($e->getRetryAfter());
             retry();
         }
         throw $e;
     }
     

4. SSL/TLS Issues:

   • If you encounter SSL errors, ensure your PHP environment includes the root CA bundle. The library bundles a root cert, but some systems (e.g., Windows) may still need manual configuration:

     $vimeo = new Vimeo($clientId, $clientSecret, $accessToken, [
         'curl' => [
             'CURLOPT_CAINFO' => __DIR__ . '/path/to/cacert.pem',
         ],
     ]);
     

5. Webhook Validation:

   • Always validate webhook signatures to prevent spoofing:

     $signature = $_SERVER['HTTP_VIMEO_SIGNATURE'] ?? '';
     $payload = file_get_contents('php://input');
     if (!$vimeo->validateWebhookSignature($signature, $payload)) {
         abort(403, 'Invalid webhook signature');
     }
     

Debugging Tips

1. Enable Verbose Logging: Pass a custom LoggerInterface to the Vimeo client:

   use Psr\Log\LoggerInterface;
   
   $logger = new class implements LoggerInterface {
       public function log($level, $message, array $context = []) {
           error_log($message);
       }
       // ... (implement other methods)
   };
   
   $vimeo = new Vimeo($clientId, $clientSecret, $accessToken, [
       'logger' => $logger,
   ]);
   

2. Inspect Raw Responses: Access the raw response object for debugging:

   $response = $vimeo->request('/me/videos');
   \Log::debug('Status: ' . $response->status);
   \Log::debug('Headers: ' . print_r($response->headers, true));
   \Log::debug('Body: ' . print_r($response->body, true));
   

3. Handle Deprecation Warnings:

   • The library drops support for PHP <7.1. Ensure your Laravel app uses PHP 7.1+.
   • Monitor deprecation notices in logs and update the library proactively.

Extension Points

1. Custom HTTP Client: Replace the default Guzzle client:

   use GuzzleHttp\Client;
   use Vimeo\Vimeo;
   
   $client = new Client(['base_uri' => 'https://api.vimeo.com/']);
   $vimeo = new Vimeo($clientId, $clientSecret, $accessToken, [
       'client' => $client,
   ]);
   

2. Proxy Support: Route requests through a