Placeholder Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bernhard-webstudio/placeholder-bundle
   

   For Symfony Flex projects, the bundle auto-registers. For non-Flex projects, add to config/bundles.php:

   return [
       // ...
       Bernhard\PlaceholderBundle\PlaceholderBundle::class => ['all' => true],
   ];
   

2. Basic Configuration: Edit config/packages/placeholder.yaml (auto-generated) to define placeholder paths and settings:

   placeholder:
       path: '%kernel.project_dir%/public/placeholders'
       width: 300
       height: 200
       text: 'Placeholder'
       color: '#eee'
   

3. First Use Case: Generate a placeholder in a controller:

   use Bernhard\PlaceholderBundle\PlaceholderGenerator;
   
   public function showImage(PlaceholderGenerator $generator)
   {
       $url = $generator->generate('user-avatar.jpg');
       return new Response($url);
   }
   

Where to Look First

• Twig Integration: Check templates/placeholder.html.twig (if auto-generated) for template overrides.
• Configuration: Review config/packages/placeholder.yaml for default values and customization.
• Generator Service: Explore PlaceholderGenerator in src/PlaceholderBundle/PlaceholderGenerator.php for API details.

Implementation Patterns

Core Workflows

1. Dynamic Placeholder Generation: Use the PlaceholderGenerator service in controllers/services to create placeholders on-the-fly:

   $generator->generate('filename.ext', [
       'width' => 800,
       'height' => 600,
       'text' => 'Custom Text',
       'color' => '#f0f0f0'
   ]);
   

2. Twig Integration: Pass the generator to Twig templates or use the placeholder() Twig function:

   <img src="{{ placeholder('image.jpg') }}" alt="Placeholder">
   

   Override the default template by creating templates/placeholder/placeholder.html.twig.

3. URL-Only Usage: Generate a direct URL for placeholders (e.g., for <img> tags or API responses):

   $url = $generator->getUrl('image.jpg');
   

4. Pregeneration: Pre-generate placeholders for static assets (e.g., during deployment):

   php bin/console placeholder:generate --filename=product.jpg --width=400 --height=300
   

   Or programmatically:

   $this->get('placeholder.generator')->pregenerate('product.jpg');
   

Integration Tips

• Symfony Forms: Use placeholders for file uploads:

  $builder->add('image', FileType::class, [
      'attr' => ['placeholder' => $generator->getUrl('default-avatar.jpg')],
  ]);
  

• API Responses: Return placeholder URLs in JSON responses for missing images:

  return ['image_url' => $generator->getUrl('fallback.jpg')];
  

• Cache Control: Leverage Symfony’s cache system to store generated placeholders (e.g., in var/cache):

  # config/packages/framework.yaml
  framework:
      cache:
          app: cache.adapter.filesystem
  

Gotchas and Tips

Pitfalls

1. Path Configuration:

   • Ensure placeholder.path in config/packages/placeholder.yaml is writable by the web server.
   • Defaults to public/placeholders; adjust if using a custom directory (e.g., var/placeholders).
   • Fix: Run chmod -R 775 public/placeholders or configure umask in your web server.

2. Image Overwrite:

   • The bundle regenerates placeholders for the same filename with new parameters. This may cause unexpected behavior if not handled.
   • Workaround: Append a unique query string to filenames:

     $url = $generator->getUrl('image.jpg') . '?v=' . uniqid();
     

3. GD Library Dependency:

   • The bundle relies on PHP’s GD library for image generation. Ensure it’s installed:

     sudo apt-get install php-gd  # Debian/Ubuntu
     sudo dnf install php-gd      # Fedora/RHEL
     

   • Debugging: Check for errors like Call to undefined function imagecreatetruecolor().

4. Twig Auto-escaping:

   • Placeholder URLs in Twig may be escaped. Use the |raw filter if needed:

     <img src="{{ placeholder('image.jpg')|raw }}">
     

Debugging

• Log Generation: Enable debug mode to log placeholder generation:

  # config/packages/dev/placeholder.yaml
  placeholder:
      debug: true
  

  Check var/log/dev.log for generation details.

• Missing Files: If placeholders aren’t generated, verify:

  • The PlaceholderGenerator service is autowired correctly.
  • The placeholder.path directory exists and is writable.
  • No PHP errors are suppressed (check error_log).

Extension Points

1. Custom Templates: Override the default Twig template by creating:

   templates/placeholder/placeholder.html.twig
   

   Extend the base template with additional logic (e.g., dynamic text or colors).

2. Custom Generators: Create a subclass of PlaceholderGenerator to add logic (e.g., watermarks):

   namespace App\Placeholder;
   
   use Bernhard\PlaceholderBundle\PlaceholderGenerator as BaseGenerator;
   
   class CustomGenerator extends BaseGenerator {
       public function generateWithWatermark(string $filename, array $options = []): string {
           $url = parent::generate($filename, $options);
           // Add watermark logic here
           return $url . '?watermark=true';
       }
   }
   

   Register the service in config/services.yaml:

   services:
       App\Placeholder\CustomGenerator: '@placeholder.generator'
   

3. Event Listeners: Listen for placeholder generation events (e.g., to log or modify parameters):

   use Bernhard\PlaceholderBundle\Event\PlaceholderGenerateEvent;
   use Symfony\Component\EventDispatcher\GenericEvent;
   
   public static function getSubscribedEvents() {
       return [
           PlaceholderGenerateEvent::NAME => 'onPlaceholderGenerate',
       ];
   }
   
   public function onPlaceholderGenerate(PlaceholderGenerateEvent $event) {
       $event->setText('Custom Text');
   }
   

4. Configuration Overrides: Dynamically override configuration per environment or route:

   $generator->setOptions(['width' => 1200, 'height' => 800]);
   $url = $generator->generate('image.jpg');