Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require vimeo/laravel
   

   Laravel 5.5+ auto-discovers the package; otherwise, add Vimeo\Laravel\VimeoServiceProvider::class to config/app.php.

2. Configuration: Publish the config file:

   php artisan vendor:publish --provider="Vimeo\Laravel\VimeoServiceProvider"
   

   Update .env with your Vimeo credentials:

   VIMEO_CLIENT_ID=your_client_id
   VIMEO_CLIENT_SECRET=your_client_secret
   VIMEO_ACCESS_TOKEN=your_access_token
   

3. First Use Case: Fetch a user’s videos via the facade:

   use Vimeo\Laravel\Facades\Vimeo;
   
   $videos = Vimeo::request('/me/videos', ['per_page' => 10], 'GET');
   

Implementation Patterns

Core Workflows

1. API Requests: Use the facade or service container for REST calls:

   // Facade
   $response = Vimeo::request('/videos/123', [], 'GET');
   
   // Service Container
   $vimeo = app('vimeo');
   $response = $vimeo->request('/videos/123', [], 'GET');
   

2. Uploads:

   • Videos:

     Vimeo::upload('/path/to/video.mp4', [
         'name' => 'My Video',
         'description' => 'A test upload'
     ]);
     

   • Images:

     Vimeo::uploadImage('/videos/123/images', '/path/to/image.jpg', true);
     

3. Webhooks: Register a webhook endpoint in routes/web.php:

   Route::post('/vimeo/webhook', 'VimeoWebhookController@handle');
   

   Configure the webhook in .env:

   VIMEO_WEBHOOK_SECRET=your_secret
   VIMEO_WEBHOOK_URL=https://your-app.test/vimeo/webhook
   

4. Pagination: Handle paginated responses with nextPageUri():

   $response = Vimeo::request('/me/videos', ['per_page' => 50], 'GET');
   while ($response->nextPageUri()) {
       $response = Vimeo::request($response->nextPageUri());
   }
   

Integration Tips

• Laravel Models: Attach Vimeo videos to Eloquent models via relationships or accessors:

  public function getVimeoVideoAttribute()
  {
      return Vimeo::request("/videos/{$this->vimeo_id}", [], 'GET');
  }
  

• Jobs/Queues: Offload uploads to a queue for async processing:

  dispatch(new UploadVimeoVideo($localPath, $videoData));
  

• Testing: Mock the Vimeo service in tests:

  $this->app->instance('vimeo', Mockery::mock('Vimeo\Laravel\VimeoManager'));
  

Gotchas and Tips

Pitfalls

1. Token Expiry:

   • Access tokens expire. Handle 401 Unauthorized errors by refreshing the token via OAuth flow.
   • Use Vimeo::refreshToken() if implementing custom OAuth logic.

2. Rate Limits:

   • Vimeo enforces rate limits (e.g., 100 requests/minute). Cache responses aggressively:

     $videos = Cache::remember("vimeo_videos_{$userId}", now()->addHours(1), function () {
         return Vimeo::request("/users/{$userId}/videos", [], 'GET');
     });
     

3. Webhook Verification:

   • Always verify webhook signatures:

     $payload = file_get_contents('php://input');
     $signature = $_SERVER['HTTP_VIMEO_SIGNATURE'];
     if (!Vimeo::verifyWebhook($payload, $signature)) {
         abort(403, 'Invalid signature');
     }
     

4. File Size Limits:

   • Vimeo has upload size limits (e.g., 5GB for Pro accounts). Stream large files to avoid memory issues:

     $stream = fopen('/path/to/large-video.mp4', 'r');
     Vimeo::uploadStream('/videos', $stream, [
         'name' => 'Large Video',
     ]);
     

Debugging

• Enable Debug Mode: Set VIMEO_DEBUG=true in .env to log raw API responses.

• Common Errors:

  • 400 Bad Request: Validate payloads (e.g., name is required for uploads).
  • 403 Forbidden: Check token permissions or IP restrictions.
  • 500 Server Error: Retry transient failures with exponential backoff.

Extension Points

1. Custom Responses: Extend the VimeoResponse class to add domain-specific logic:

   class CustomVimeoResponse extends \Vimeo\Laravel\VimeoResponse
   {
       public function getDuration()
       {
           return $this->data['duration'] ?? 0;
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind('vimeo.response', function () {
       return new CustomVimeoResponse();
   });
   

2. Middleware: Add middleware to transform responses globally:

   Vimeo::extend(function ($vimeo) {
       $vimeo->after(function ($response) {
           $response->data = collect($response->data)->map(function ($item) {
               $item['custom_field'] = 'value';
               return $item;
           });
       });
   });
   

3. OAuth Flow: For custom OAuth (e.g., user-specific tokens), implement a TokenManager:

   class UserTokenManager
   {
       public function getTokenForUser(User $user)
       {
           return $user->vimeo_token ?? config('vimeo.default_token');
       }
   }
   

   Bind it to the Vimeo manager:

   $this->app->bind('vimeo.token_manager', function () {
       return new UserTokenManager();
   });