Services Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require c975l/services-bundle
   

   Ensure your Laravel project is using Laravel 5.4+ (as the bundle is Symfony-based, but Laravel 5.4+ supports Symfony bundles via illuminate/foundation).

2. Register the Bundle Add the bundle to config/app.php under the providers array:

   'providers' => [
       // ...
       c975L\ServicesBundle\c975LServicesBundle::class,
   ],
   

3. First Use Case: Image Resizing Inject ServiceImageInterface into a controller or service:

   use c975L\ServicesBundle\Service\ServiceImageInterface;
   
   public function resizeImage(ServiceImageInterface $imageService) {
       $imageService->resize(
           $file,          // Uploaded file (e.g., from `request()->file('image')`)
           'uploads',      // Target folder
           'resized.jpg',  // Output filename
           'jpg',          // Format
           400,            // Final height
           75,             // Compression (0-100)
           false,          // Square crop?
           null            // Optional stamp image
       );
   }
   

Where to Look First

• API Docs – Reference for all services/interfaces.
• src/Service/ – Core service implementations (e.g., ServiceImage, ServiceTranslation).
• Resources/translations/ – Predefined translations (if leveraging the bundle’s i18n features).

Implementation Patterns

Dependency Injection

• Type-Hint Interfaces: Always inject interfaces (e.g., ServiceImageInterface) for testability and flexibility.

  public function __construct(ServiceImageInterface $imageService) {
      $this->imageService = $imageService;
  }
  

• Service Binding: Override bindings in AppServiceProvider if extending functionality:

  $this->app->bind(ServiceImageInterface::class, function ($app) {
      return new CustomImageService(); // Your wrapper
  });
  

Common Workflows

1. Image Processing

   • Resize: Use resize() for dynamic thumbnails.
   • Watermark: Pass a stamp image (PNG/SVG) via $stamp parameter.
   • Validation: Check file types with isValidImage() before processing.

2. Translations

   • Extend the bundle’s translation system by adding new .po/.mo files to Resources/translations/ and clear Laravel’s cache:

     php artisan view:clear
     php artisan config:clear
     

3. Shell Scripts

   • The bundle includes .sh scripts (e.g., for deployment). Use them via Laravel’s Artisan::call():

     Artisan::call('vendor:bin/services-bundle/script.sh', ['arg1' => 'value']);
     

Integration Tips

• Laravel Filesystem: Store processed images in Laravel’s storage:

  use Illuminate\Support\Facades\Storage;
  Storage::disk('public')->put('path/resized.jpg', $imageData);
  

• Queue Jobs: Offload heavy operations (e.g., image resizing) to queues:

  dispatch(new ResizeImageJob($file, $params));
  

• Validation: Combine with Laravel’s validation:

  $request->validate(['image' => 'required|image|mimes:jpeg,png']);
  

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel Compatibility

   • The bundle assumes Symfony’s Kernel and Container. In Laravel, ensure:
     • illuminate/foundation is up-to-date.
     • Avoid direct Container calls; use Laravel’s DI instead.
   • Fix: Wrap service calls in a Laravel-compatible facade or service class.

2. Translation Overrides

   • Laravel’s translation system may conflict with the bundle’s .po files. Solution:
     • Prepend your domain to translation keys (e.g., services::key).
     • Use Laravel’s trans() helper with the services namespace:

       trans('services::message.key');
       

3. File Path Handling

   • The bundle expects absolute paths for $folder in resize(). Tip:
     • Use Laravel’s storage_path() or public_path():

       $folder = storage_path('app/uploads');
       

4. Image Format Limitations

   • The resize() method defaults to jpg. For lossless formats (e.g., webp), ensure:
     • The imagick PHP extension is installed.
     • Pass the correct $format (e.g., 'webp').

Debugging

• Service Not Found: Verify the bundle is registered in config/app.php and dependencies are installed.
• Translation Missing: Check if the .po file exists in Resources/translations/ and the locale is loaded.
• Image Errors: Validate file permissions and GD/Imagick extensions:

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

Extension Points

1. Custom Services

   • Extend interfaces (e.g., ServiceImageInterface) and bind them in AppServiceProvider:

     $this->app->extend(ServiceImageInterface::class, function ($service) {
         return new CustomImageService($service);
     });
     

2. Adding Translations

   • Place new .po files in Resources/translations/ and update the bundle’s Resources/config/translations.php to include them:

     return [
         'en' => 'path/to/en.po',
         'fr' => 'path/to/fr.po',
     ];
     

3. Shell Script Integration

   • Call scripts via Artisan commands or Laravel’s Process facade:

     use Symfony\Component\Process\Process;
     $process = new Process(['bash', 'vendor/bin/services-bundle/script.sh']);
     $process->run();
     

Performance Tips

• Cache Translations: Laravel caches translations by default. For dynamic bundles, use:

  app('translator')->setFallback(false);
  

• Batch Processing: Use Laravel’s collect() to process multiple images:

  $files->each(function ($file) use ($imageService) {
      $imageService->resize($file, 'uploads', $file->hashName());
  });