Webp Conversion Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require 094ikis09/webp-conversion-bundle
   

   Ensure the bundle is enabled in config/bundles.php (Symfony auto-discovers it).

2. First Conversion: Run the command to scan and convert images in a directory (dry run first):

   php bin/console codebuds:webp:convert public/uploads
   

   Then execute the actual conversion:

   php bin/console codebuds:webp:convert --create --quality=80 public/uploads
   

3. Twig Integration: Add the Twig extension to your templates (check config/packages/twig.yaml for auto-registration). Use the filter in <picture> tags:

   <picture>
       <source srcset="{{ '/images/photo.jpg' | cb_webp }}" type="image/webp">
       <img src="{{ '/images/photo.jpg' }}" alt="Fallback">
   </picture>
   

Implementation Patterns

Workflows

1. Batch Conversion:

   • Use the --create flag to generate .webp files in bulk (e.g., during deployments or asset updates).
   • Schedule via Laravel’s schedule:run or Symfony’s cron for periodic optimization:

     * * * * * php bin/console codebuds:webp:convert --create --quality=75 /path/to/images
     

2. Dynamic Quality:

   • Adjust --quality per directory (e.g., higher for hero images, lower for thumbnails):

     php bin/console codebuds:webp:convert --create --quality=95 public/hero --quality=60 public/thumbs
     

3. VichUploader/LiipImagine Integration:

   • For dynamically uploaded images (e.g., via VichUploader), combine with cb_webp filter in Twig:

     <picture>
         <source srcset="{{ asset(vich_uploader_asset.image) | cb_webp }}" type="image/webp">
         <img src="{{ asset(vich_uploader_asset.image) }}" alt="{{ image.name }}">
     </picture>
     

   • For LiipImagine filters, chain the cb_webp filter after the filter name:

     {{ 'image.jpg' | liip_imagine_filter('thumbnail') | cb_webp }}
     

4. Fallback Handling:

   • Use the <img> tag inside <picture> for graceful degradation (works even if WebP isn’t supported).

Integration Tips

• Storage: Store converted .webp files in a separate directory (e.g., public/uploads/webp) and update paths in Twig:

  {{ '/uploads/webp/' ~ filename ~ '_q80.webp' | asset_url }}
  

• Caching: Cache the cb_webp filter output in Twig (if using Symfony’s cache layer) to avoid reprocessing.
• Validation: Add a middleware to check for .webp existence before serving (e.g., via Symfony\Component\HttpKernel\EventListener\RewriteListener).

Gotchas and Tips

Pitfalls

1. File Overwrites:

   • --force will overwrite existing .webp files. Tip: Use --suffix to version files (e.g., _v2.webp) during updates.
   • Debugging: Check var/log/dev.log for skipped files (e.g., unsupported formats or permission issues).

2. Path Handling:

   • The command expects absolute paths (e.g., public/uploads). Relative paths may fail silently.
   • Fix: Use realpath() in custom scripts or Laravel’s public_path().

3. Twig Filter Scope:

   • The cb_webp filter assumes the input is a public path (e.g., /images/photo.jpg). Tip: Use asset() for asset paths:

     {{ asset('images/photo.jpg') | cb_webp }}  {# Works if filter handles asset URLs #}
     

4. Quality Trade-offs:

   • Lower quality (e.g., --quality=50) reduces file size but may degrade visual fidelity. Tip: Test with WebPageTest to balance speed vs. quality.

Debugging

• Dry Runs: Always run without --create first to verify file lists:

  php bin/console codebuds:webp:convert --debug public/uploads
  

• Permissions: Ensure the web server user (e.g., www-data) has write access to the target directory:

  chmod -R 755 public/uploads
  

• Unsupported Formats: The bundle skips non-JPEG/PNG/GIF/BMP files. Tip: Log unsupported formats for review:

  // In a custom command extension:
  $this->logger->info('Skipped unsupported format: ' . $file);
  

Extension Points

1. Custom Filters:

   • Extend the Twig extension to support additional formats (e.g., SVG → WebP):

     // src/Twig/Extension/WebPExtension.php
     public function getFilters()
     {
         return [
             new \Twig\TwigFilter('cb_webp_svg', [$this, 'convertSvgToWebp']),
         ];
     }
     

2. Pre/Post-Processing:

   • Hook into the conversion process via Symfony’s event system (e.g., kernel.terminate):

     # config/services.yaml
     App\EventListener\WebPPostProcessListener:
         tags:
             - { name: kernel.event_listener, event: kernel.terminate, method: onTerminate }
     

3. Laravel Integration:

   • Publish the command as a Laravel Artisan command:

     // app/Console/Commands/ConvertWebP.php
     use Symfony\Component\Console\Application;
     $app = new Application();
     $app->add(new \Codebuds\WebPConversionBundle\Command\WebPConvertCommand());