Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aperturelabo/core-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       ApertureLabo\CoreBundle\ApertureCoreBundle::class => ['all' => true],
   ];
   

2. First Use Case: Asset Management The bundle provides a LiipImagineBundle wrapper for image processing. Start by configuring it in config/packages/liip_imagine.yaml:

   liip_imagine:
       driver: gd
       filter_sets:
           thumbnail:
               quality: 75
               filters:
                   thumbnail: { size: [200, 200], mode: outbound }
   

   Use the service in a controller:

   use ApertureLabo\CoreBundle\Service\ImageService;
   
   class ImageController extends AbstractController
   {
       public function resize(ImageService $imageService, string $path): Response
       {
           return $imageService->resize($path, 'thumbnail');
       }
   }
   

3. Doctrine ORM Integration The bundle includes common Doctrine entities. Extend them in your project:

   use ApertureLabo\CoreBundle\Entity\BaseEntity;
   
   #[ORM\Entity]
   class CustomEntity extends BaseEntity
   {
       // Your custom fields
   }
   

Implementation Patterns

Workflow: Asset Pipeline

1. Upload Assets Use Symfony’s UploadedFile with a custom validator (e.g., ApertureLabo\CoreBundle\Validator\FileType):

   #[Assert\File(mimeTypes: ['image/jpeg', 'image/png'])]
   #[Assert\File(maxSize: '1024k')]
   private ?UploadedFile $image;
   

2. Process Assets Chain ImageService with LiipImagineBundle:

   $imageService->resize($filePath, 'thumbnail')
                ->optimize('webp');
   

3. Store Metadata Attach metadata to processed assets via Doctrine:

   $asset = new Asset();
   $asset->setOriginalPath($originalPath)
         ->setProcessedPath($processedPath)
         ->setMetadata(['width' => 200, 'height' => 200]);
   $entityManager->persist($asset);
   

Integration Tips

• YAML Configuration: Leverage symfony/yaml for dynamic config loading:

  $config = Yaml::parseFile(__DIR__.'/config/imagine.yaml');
  $imageService->setConfig($config);
  

• Event Listeners: Extend core events (e.g., AssetProcessedEvent) for post-processing:

  public function onAssetProcessed(AssetProcessedEvent $event): void
  {
      $event->getAsset()->setProcessedAt(new \DateTime());
  }
  

• Dependency Injection: Prefer constructor injection for ImageService and EntityManager:

  public function __construct(
      private ImageService $imageService,
      private EntityManagerInterface $em
  ) {}
  

Gotchas and Tips

Pitfalls

1. LiipImagineBundle Dependencies

   • Ensure gd or imagick PHP extensions are installed. Debug with:

     php -m | grep -E 'gd|imagick'
     

   • If using Docker, add to Dockerfile:

     RUN docker-php-ext-install gd
     

2. Doctrine Entity Inheritance

   • Avoid overriding BaseEntity methods unless necessary. Use traits for reusable logic:

     trait SoftDeletable {
         public function isDeleted(): bool { /* ... */ }
     }
     

3. YAML Parsing Quirks

   • Use Yaml::parse() for arrays, Yaml::parseFile() for files. Unescaped keys may cause issues:

     # ❌ Fails (unquoted key with special chars)
     filter_sets:
         thumbnail@2x: { ... }
     
     # ✅ Works
     filter_sets:
         "thumbnail@2x": { ... }
     

Debugging

• Image Processing Errors Check LiipImagineBundle logs in var/log/dev.log for filter failures. Validate input paths:

  if (!file_exists($path)) {
      throw new \RuntimeException("File not found: {$path}");
  }
  

• Doctrine Events Disable listeners during tests:

  $this->entityManager->getEventManager()->removeEventListeners();
  

Extension Points

1. Custom Filters Extend ImageService to add filters:

   class CustomImageService extends ImageService
   {
       public function addWatermark(string $path, string $watermarkPath): string
       {
           // Implement logic
       }
   }
   

   Register as a service in services.yaml:

   services:
       App\Service\CustomImageService:
           decorates: aperturelabo.core.image_service
   

2. Asset Metadata Add custom metadata fields to Asset entity:

   #[ORM\Column(type: 'json', nullable: true)]
   private ?array $customMetadata = [];
   

   Use json type for flexibility in Doctrine 2.10+.