Pdfcrowd Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   • Add the package via Composer (as per the archived repo, ensure you handle the custom pdfcrowd-php dependency manually).
   • Register the bundle in AppKernel.php:

     new Amp\PDFCrowdBundle\AmpPDFCrowdBundle(),
     

   • Configure credentials in config.yml:

     amp_pdf_crowd:
         username: %env(PDFCROWD_USERNAME)%
         apikey: %env(PDFCROWD_APIKEY)%
     

2. First Use Case: Convert a URL to PDF in a controller:

   use Amp\PDFCrowdBundle\PDFCrowd\PDFCrowd;
   
   public function generatePdfAction()
   {
       $pdfCrowd = $this->get('amp_pdf_crowd.api');
       $url = $this->generateUrl('route_name', [], true);
       $pdfData = $pdfCrowd->convertURI($url);
   
       return new Response($pdfData, 200, [
           'Content-Type' => 'application/pdf',
           'Content-Disposition' => 'inline; filename="document.pdf"',
       ]);
   }
   

3. Key Files:

   • src/Amp/PDFCrowdBundle/Resources/config/services.yml (Service definitions).
   • src/Amp/PDFCrowdBundle/PDFCrowd/PDFCrowd.php (Core API wrapper).

Implementation Patterns

Common Workflows

1. URL-to-PDF Conversion:

   $pdfCrowd = $this->get('amp_pdf_crowd.api');
   $pdfData = $pdfCrowd->convertURI('https://example.com');
   file_put_contents('path/to/file.pdf', $pdfData);
   

2. HTML-to-PDF Conversion:

   $html = '<h1>Hello World</h1>';
   $pdfData = $pdfCrowd->convertHTML($html);
   

3. Streaming PDFs:

   $response = new Response($pdfData, 200, [
       'Content-Type' => 'application/pdf',
   ]);
   return $response;
   

4. CLI Conversion (via Symfony Command):

   php bin/console pdfcrowd:convert https://example.com public/pdfs/output.pdf
   

Integration Tips

• Environment Variables: Use .env for credentials (e.g., PDFCROWD_USERNAME).
• Error Handling: Wrap API calls in try-catch blocks:

  try {
      $pdfData = $pdfCrowd->convertURI($url);
  } catch (\Exception $e) {
      $this->addFlash('error', 'PDF generation failed: ' . $e->getMessage());
      return $this->redirectToRoute('home');
  }
  

• Caching: Cache generated PDFs to avoid redundant API calls:

  $cache = $this->get('cache.app');
  $cacheKey = 'pdf_' . md5($url);
  if (!$cache->has($cacheKey)) {
      $pdfData = $pdfCrowd->convertURI($url);
      $cache->set($cacheKey, $pdfData, 3600); // Cache for 1 hour
  } else {
      $pdfData = $cache->get($cacheKey);
  }
  

• Batch Processing: Use Symfony’s EventDispatcher to queue PDF jobs (e.g., for invoices).

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.x:

   • The bundle targets Symfony 2.x. If using Symfony 3/4/5, expect compatibility issues (e.g., service container changes).
   • Fix: Override service definitions in config/services.yml or use a compatibility layer like symfony/symfony-bridge.

2. Custom pdfcrowd-php Dependency:

   • The package requires manually adding pdfcrowd-php via Composer’s repositories (as shown in the README).
   • Fix: Use a script in composer.json to automate downloads:

     "scripts": {
         "post-install-cmd": [
             "php vendor/bin/pdfcrowd-downloader"
         ]
     }
     

3. File Permissions:

   • Ensure the target directory for PDFs is writable (e.g., chmod -R 775 var/).

4. API Rate Limits:

   • PDFCrowd has rate limits. Handle PDFCrowdException for throttling:

     catch (\Amp\PDFCrowdBundle\PDFCrowd\PDFCrowdException $e) {
         if ($e->getCode() === 429) {
             // Retry or notify admin
         }
     }
     

5. Deprecated Methods:

   • The bundle may use outdated PDFCrowd API methods (e.g., convertURI vs. newer SDK methods).
   • Fix: Extend the PDFCrowd class to wrap the latest SDK:

     class ExtendedPDFCrowd extends \Amp\PDFCrowdBundle\PDFCrowd\PDFCrowd {
         public function convertUrl(string $url) {
             return $this->client->convertUrl($url);
         }
     }
     

Debugging Tips

1. Enable Debug Mode:

   • Set PDFCROWD_DEBUG: true in .env to log API responses:

     amp_pdf_crowd:
         debug: %env(bool:PDFCROWD_DEBUG)%
     

2. Log API Errors:

   • Extend the PDFCrowd class to log exceptions:

     public function convertURI($uri) {
         try {
             return parent::convertURI($uri);
         } catch (\Exception $e) {
             $this->logger->error('PDFCrowd error: ' . $e->getMessage());
             throw $e;
         }
     }
     

3. Test Locally:

   • Use PDFCrowd’s sandbox for testing before going live.

Extension Points

1. Custom PDF Options:

   • Extend the bundle to support PDFCrowd’s advanced options (e.g., margins, headers):

     $pdfCrowd->setOption('margin-top', '20mm');
     $pdfData = $pdfCrowd->convertURI($url);
     

2. Event Listeners:

   • Dispatch events for PDF generation (e.g., pdfcrowd.pre_convert):

     // In services.yml
     amp_pdf_crowd.api:
         class: Amp\PDFCrowdBundle\PDFCrowd\PDFCrowd
         calls:
             - [setEventDispatcher, ['@event_dispatcher']]
     

3. Storage Adapters:

   • Replace file_put_contents with a custom storage service (e.g., S3):

     $storage = $this->get('storage_service');
     $storage->save('pdfs/example.pdf', $pdfData);
     

4. Fallback Mechanisms:

   • Implement a fallback to a local library (e.g., Dompdf) if PDFCrowd fails:

     try {
         $pdfData = $pdfCrowd->convertURI($url);
     } catch (\Exception $e) {
         $pdfData = $this->fallbackConverter->convert($url);
     }