Swissarmyknife Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require aldaflux/swissarmyknife-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       AldaFlux\SwissArmyKnifeBundle\AldaFluxSwissArmyKnifeBundle::class => ['all' => true],
   ];
   

2. First Use Case: Image Optimization The bundle provides a ImageOptimizer service. Inject it into a controller or service:

   use AldaFlux\SwissArmyKnifeBundle\Service\ImageOptimizer;
   
   class MyController extends AbstractController
   {
       public function optimizeImage(ImageOptimizer $optimizer)
       {
           $path = $this->getParameter('kernel.project_dir') . '/public/uploads/image.jpg';
           $optimizer->optimize($path);
           return new Response('Image optimized!');
       }
   }
   

3. First Use Case: Documentation Generation Use the DocGenerator service to generate documentation from Twig templates:

   use AldaFlux\SwissArmyKnifeBundle\Service\DocGenerator;
   
   class MyController extends AbstractController
   {
       public function generateDocs(DocGenerator $generator)
       {
           $output = $generator->generate('path/to/templates', 'path/to/output');
           return new Response($output);
       }
   }
   

Implementation Patterns

Common Workflows

1. Image Handling

   • Resizing: Use ImageOptimizer for resizing with predefined or custom dimensions:

     $optimizer->resize($path, 800, 600);
     

   • Compression: Optimize images for web:

     $optimizer->compress($path, 80); // 80% quality
     

   • Batch Processing: Loop through an array of paths:

     foreach ($imagePaths as $path) {
         $optimizer->optimize($path);
     }
     

2. Documentation

   • Twig-Based Docs: Pass Twig templates and data to generate HTML:

     $data = ['title' => 'My API', 'endpoints' => [...]];
     $generator->generate('templates/docs', 'public/docs', $data);
     

   • Markdown Support: Convert Markdown to HTML (if supported):

     $markdown = file_get_contents('README.md');
     $html = $generator->markdownToHtml($markdown);
     

3. Integration with Symfony

   • Event Listeners: Trigger optimizations on file uploads:

     // src/EventListener/ImageUploadListener.php
     class ImageUploadListener implements KernelEventListener
     {
         public function __construct(private ImageOptimizer $optimizer) {}
     
         public function onKernelRequest(GetResponseEvent $event)
         {
             if ($event->isMainRequest()) {
                 $this->optimizer->optimizeUploadedFiles($_FILES);
             }
         }
     }
     

   • Twig Extensions: Extend Twig with custom filters (e.g., for image paths):

     {{ asset(optimize_path(imagePath, 300)) }}
     

     Register in services.yaml:

     services:
         AldaFlux\SwissArmyKnifeBundle\Twig\OptimizeExtension:
             tags: ['twig.extension']
     

4. Configuration

   • Override default settings in config/packages/alda_flux_swiss_army_knife.yaml:

     alda_flux_swiss_army_knife:
         image_optimizer:
             default_quality: 75
             allowed_formats: ['jpg', 'png', 'webp']
         doc_generator:
             output_format: 'html'
     

Gotchas and Tips

Pitfalls

1. PHP Version Compatibility

   • The bundle requires PHP 5.3.2+, but modern Symfony (5.4+) uses PHP 7.4+. Test thoroughly if using older PHP versions.
   • Fix: Use a PHP 7.4+ environment for development.

2. Missing Dependencies

   • The bundle requires symfony/framework-bundle:>=3.0, but some features (e.g., Twig extensions) may fail on older Symfony versions.
   • Fix: Ensure your composer.json aligns with Symfony 3.0+ requirements.

3. Image Optimization Dependencies

   • The ImageOptimizer likely relies on external tools like imagemagick or gd. Missing these will cause failures.
   • Fix: Install dependencies:

     sudo apt-get install imagemagick  # Linux
     brew install imagemagick         # macOS
     

4. Twig Template Paths

   • The DocGenerator assumes templates exist in specific paths. Hardcoded paths may break in custom setups.
   • Fix: Use absolute paths or configure the bundle to resolve paths relative to kernel.project_dir.

5. No Clear Service Naming

   • The bundle lacks explicit service names in documentation, making autowiring ambiguous.
   • Fix: Use debug:container to inspect service IDs:

     php bin/console debug:container AldaFlux
     

Debugging Tips

1. Enable Debug Mode Add this to config/packages/dev/alda_flux_swiss_army_knife.yaml:

   alda_flux_swiss_army_knife:
       debug: true
   

   This may log additional info to var/log/dev.log.

2. Check for Exceptions Wrap service calls in try-catch blocks:

   try {
       $optimizer->optimize($path);
   } catch (\Exception $e) {
       $this->addFlash('error', 'Image optimization failed: ' . $e->getMessage());
   }
   

3. Verify File Permissions Ensure the output directory for generated docs has write permissions:

   chmod -R 775 public/docs
   

Extension Points

1. Custom Image Filters Extend the ImageOptimizer by creating a decorator:

   services:
       app.image_optimizer.decorator:
           decorates: alda_flux_swiss_army_knife.image_optimizer
           arguments: ['@app.image_optimizer.decorator.inner']
   

   Then implement logic in a custom service.

2. Add New Doc Formats If the DocGenerator lacks support for a format (e.g., PDF), create a new service and integrate it via Symfony’s compiler passes.

3. Override Twig Extensions Replace or extend existing Twig extensions by redefining them in services.yaml:

   services:
       AldaFlux\SwissArmyKnifeBundle\Twig\OptimizeExtension:
           class: App\Twig\CustomOptimizeExtension
           tags: ['twig.extension']
   

Configuration Quirks

1. Default Values The bundle may use hardcoded defaults (e.g., default_quality: 80). Override them explicitly in your config to avoid surprises.

2. Caching If the DocGenerator caches output, clear the cache after updates:

   php bin/console cache:clear
   

3. Environment-Specific Settings Use %kernel.environment% to conditionally load configs:

   alda_flux_swiss_army_knife:
       image_optimizer:
           default_quality: %env(int:IMAGE_QUALITY, 75)%