Api Client Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require qencode/api-client:^1.13
   

   Verify autoloading by requiring vendor/autoload.php in your entry point.

2. First Use Case: Initialize the client with your API key:

   $client = new \QencodeApiClient('your_api_key_here');
   

3. Basic Workflow:

   • Create a transcoding task:

     $task = $client->createTask();
     $task->start($profileId, 'https://example.com/video.mp4');
     

   • Poll for status:

     $status = $task->getStatus();
     

4. Key Files to Reference:

   • src/QencodeApiClient.php (core client logic)
   • src/Task.php (task management methods)
   • src/Exceptions/ (error handling)

Implementation Patterns

Core Workflows

1. Task Lifecycle Management:

   // Create and trigger a task
   $task = $client->createTask();
   $task->start($profileId, $sourceUrl, ['output' => 's3://bucket/output.mp4']);
   
   // Monitor progress
   while ($task->getStatus()['status'] !== 'finished') {
       sleep(5);
   }
   

2. Batch Processing:

   $tasks = [];
   foreach ($videoUrls as $url) {
       $task = $client->createTask();
       $task->start($profileId, $url);
       $tasks[] = $task;
   }
   

3. Error Handling:

   try {
       $task->start($profileId, $sourceUrl);
   } catch (\QencodeApiClientException $e) {
       \Log::error('Transcoding failed:', ['error' => $e->getMessage()]);
       // Retry logic or fallback
   }
   

Integration Tips

• Laravel Service Provider: Bind the client to the container for dependency injection:

  $this->app->singleton(QencodeApiClient::class, function ($app) {
      return new QencodeApiClient(config('services.qencode.key'));
  });
  

• Queue Jobs: Dispatch long-running tasks to Laravel queues:

  TranscodeJob::dispatch($client, $profileId, $sourceUrl, $outputPath);
  

• Configuration: Store API key in .env:

  QENCODE_API_KEY=your_key_here
  

  Load via config:

  $client = new QencodeApiClient(config('qencode.key'));
  

Gotchas and Tips

Pitfalls

1. Rate Limiting:

   • Qencode API enforces rate limits (e.g., 100 requests/minute).
   • Cache responses for repeated calls (e.g., getStatus()).
   • Use exponential backoff for retries:

     $retryAfter = $e->getRetryAfter();
     sleep($retryAfter);
     

2. Task Timeouts:

   • Long-running tasks may fail silently. Implement a heartbeat check:

     if ($task->getStatus()['status'] === 'processing' && $task->getDuration() > 3600) {
         $task->cancel(); // Abort if stuck
     }
     

3. API Key Exposure:

   • Never hardcode keys. Use Laravel's config() or environment variables.
   • Restrict key permissions in Qencode dashboard to only necessary endpoints.

Debugging

• Enable Verbose Logging:

  $client = new QencodeApiClient($apiKey, [
      'debug' => true,
      'logger' => new \Monolog\Logger('qencode')
  ]);
  

• Common HTTP Errors:

  • 401 Unauthorized: Invalid API key or expired token.
  • 429 Too Many Requests: Hit rate limit. Check Retry-After header.
  • 500 Internal Server Error: Contact Qencode support with task ID.

Extension Points

1. Custom Profiles:

   • Extend Task to add profile validation:

     class CustomTask extends \Qencode\Task {
         public function start($profileId, $source, array $options = []) {
             if (!in_array($profileId, config('qencode.allowed_profiles'))) {
                 throw new \InvalidArgumentException('Profile not allowed');
             }
             parent::start($profileId, $source, $options);
         }
     }
     

2. Webhook Integration:

   • Use Qencode’s webhook API to trigger Laravel events:

     Route::post('/qencode-webhook', function (Request $request) {
         event(new \Qencode\Events\TaskCompleted($request->input()));
     });
     

3. Mocking for Tests:

   • Stub the client in PHPUnit:

     $mock = Mockery::mock(QencodeApiClient::class)->makePartial();
     $mock->shouldReceive('createTask')->andReturnSelf();
     $mock->shouldReceive('start')->once();
     

Configuration Quirks

• Endpoint Overrides:

  • Default endpoint is https://api.qencode.com. Override in constructor:

    $client = new QencodeApiClient($apiKey, ['endpoint' => 'https://custom.qencode.com']);
    

• SSL Verification:

  • Disable for self-signed certs (not recommended for production):

    $client = new QencodeApiClient($apiKey, ['verify_ssl' => false]);