Zendservice Livedocx Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (if still needed for legacy projects):

   composer require zendframework/zendservice-livedocx
   

   (Note: Due to archival, ensure compatibility with your Laravel version—likely ZF2-era projects.)

2. Service Initialization Register the LiveDocx client in Laravel’s config/services.php:

   'livedocx' => [
       'api_key' => env('LIVEDOCX_API_KEY'),
       'account_id' => env('LIVEDOCX_ACCOUNT_ID'),
       'endpoint' => env('LIVEDOCX_ENDPOINT', 'https://api.livedocx.com'),
   ],
   

   Bind the service in AppServiceProvider:

   $this->app->singleton('livedocx', function ($app) {
       $config = $app['config']['services.livedocx'];
       return new \ZendService\LiveDocx\Client($config['api_key'], $config['account_id'], $config['endpoint']);
   });
   

3. First Use Case: Generate a Document Inject the client into a controller/service and call the API:

   use ZendService\LiveDocx\Client;
   
   public function generateDocument(Client $livedocx) {
       $templateId = 'your_template_id';
       $data = ['name' => 'John Doe', 'date' => now()->format('Y-m-d')];
   
       $response = $livedocx->generate($templateId, $data);
       return response()->download($response->getDocumentUrl());
   }
   

Implementation Patterns

Common Workflows

1. Template Management

   • Fetch Templates: List available templates via $livedocx->getTemplates().
   • Upload Templates: Use $livedocx->uploadTemplate($filePath, $name) for custom templates.
   • Dynamic Data Binding: Pass associative arrays to generate() for placeholders like {name}.

2. Document Operations

   • Batch Generation: Loop through templates/data pairs:

     foreach ($templates as $template) {
         $livedocx->generate($template['id'], $data)->storeAs($template['name'] . '.docx');
     }
     

   • Async Processing: Use callbacks for long-running tasks (if supported by the API).

3. Error Handling Wrap API calls in try-catch blocks:

   try {
       $result = $livedocx->generate($templateId, $data);
   } catch (\ZendService\LiveDocx\Exception\RuntimeException $e) {
       Log::error("LiveDocx Error: " . $e->getMessage());
       abort(500, "Document generation failed.");
   }
   

Integration Tips

• Laravel Filesystem: Store generated documents in storage/app/livedocx:

  $livedocx->generate($templateId, $data)->storeAs('invoices/invoice_' . $id . '.docx');
  

• Queue Jobs: Offload document generation to queues (e.g., GenerateDocumentJob):

  GenerateDocumentJob::dispatch($templateId, $data, $userId)->onQueue('livedocx');
  

• API Rate Limiting: Implement retries with exponential backoff for failed requests.

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies

   • The package relies on Zend Framework 2 (ZF2) components. Ensure compatibility with Laravel’s DI container by manually binding services.
   • Fix: Use a compatibility layer like zendframework/zend-servicemanager if needed.

2. API Key Security

   • Hardcoded API keys in config files are a risk. Use Laravel’s .env and env() helper:

     'api_key' => env('LIVEDOCX_API_KEY', 'fallback_if_needed'),
     

   • Tip: Restrict .env file permissions (chmod 600 .env).

3. Document Size Limits

   • LiveDocx may impose size limits (e.g., 50MB). Validate uploads before processing:

     if ($file->getSize() > 50 * 1024 * 1024) {
         throw new \Exception("File too large.");
     }
     

4. Rate Limits

   • The free tier has strict rate limits (e.g., 100 requests/day). Monitor usage via:

     $livedocx->getAccountUsage(); // Hypothetical; check API docs.
     

Debugging

• Enable Guzzle Logging: Add to config/services.php:

  'livedocx' => [
      'http_client' => [
          'handler' => \GuzzleHttp\HandlerStack::create([
              'debug' => function ($handler) {
                  $debugHandler = new \GuzzleHttp\Handler\CurlHandler();
                  return \GuzzleHttp\HandlerStack::create($debugHandler);
              },
          ]),
      ],
  ],
  

  Logs appear in storage/logs/laravel.log.

• Validate API Responses: Inspect raw responses for errors:

  $response = $livedocx->generate($templateId, $data);
  if ($response->hasError()) {
      Log::debug("Raw Response: " . $response->getRawBody());
  }
  

Extension Points

1. Custom Response Handlers Extend the client to handle responses differently:

   class CustomLiveDocxClient extends \ZendService\LiveDocx\Client {
       public function generate($templateId, $data) {
           $response = parent::generate($templateId, $data);
           return new CustomDocumentResponse($response->getDocumentUrl());
       }
   }
   

2. Webhook Integration Use Laravel’s queue:work to process webhook callbacks from LiveDocx (e.g., for async completion events).

3. Fallback Templates Implement a local fallback for offline use:

   if (!$livedocx->isOnline()) {
       return view('pdf.fallback', ['data' => $data]);
   }