Sulu Media Extra Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alengo/sulu-media-extra-bundle
   

   Register the bundle in config/bundles.php:

   Alengo\SuluMediaExtraBundle\AlengoMediaExtraBundle::class => ['all' => true],
   

2. First Use Case:

   • Enable @2x crop sync (automatic): No action required—it activates immediately after installation.
   • Generate image formats (one-time setup):

     bin/adminconsole alengo:media:image-formats:generate
     

     Create a YAML file at config/app/image-formats.yaml (see README for format).

Implementation Patterns

1. @2x Crop Synchronization

• Workflow:
  • Define @2x formats in image-formats.xml (e.g., 800x@2x).
  • Save crops for @2x formats in the Sulu admin panel.
  • The bundle automatically mirrors crop coordinates to the base format (e.g., 800x).
• Integration:
  • Useful for responsive designs where @1x and @2x crops must align.
  • Example: Add 800x@2x to your image-formats.xml and let the bundle handle the rest.

2. Image Format Generation

• Workflow:
  • Define formats in config/app/image-formats.yaml (e.g., 400x300, 800x).
  • Run the command to generate XML entries:

    bin/adminconsole alengo:media:image-formats:generate --source=config/app/image-formats.yaml
    

  • The command appends entries to config/image-formats.xml (avoids overwriting existing configs).
• Best Practice:
  • Use this for new projects or when adding standardized formats.
  • Combine with image-format-options:duplicate if migrating existing crops.

3. Backfilling Existing Crops

• Workflow:
  • If @2x crops exist but base formats lack crops, run:

    bin/adminconsole alengo:media:image-format-options:duplicate
    

  • Requires a YAML source file listing format keys (e.g., 800x, 400x300).
• Use Case:
  • Post-installation cleanup for projects with pre-existing media.

4. Media Renaming

• Workflow:
  • Rename a media file (updates DB + storage):

    bin/adminconsole alengo:media:rename <mediaId> "new-name" --locale=en
    

  • Dry-run for safety:

    bin/adminconsole alengo:media:rename <mediaId> "new-name" --dry-run
    

• Integration:
  • Useful for batch updates (e.g., correcting filenames post-upload).
  • Preserves file extensions and increments subVersion to invalidate caches.

Gotchas and Tips

Pitfalls

1. XML Overwrite Risk:

   • The image-formats:generate command appends to image-formats.xml. If you manually edit the file, conflicts may arise.
   • Fix: Back up image-formats.xml before running the command.

2. Locale Handling in Renaming:

   • The rename command uses --locale to normalize filenames (e.g., Ümlaut → Umlaut).
   • Tip: Always specify --locale explicitly to avoid unexpected behavior.

3. Dry-Run Limitations:

   • The --dry-run flag shows what would change but doesn’t validate storage permissions.
   • Test: Run dry-run first, then verify storage paths manually.

4. Circular Dependencies in Crops:

   • If base and @2x formats have conflicting crops, the bundle prioritizes @2x as the source.
   • Debug: Check me_format_options table for orphaned entries after sync.

Debugging

• Event Listener Issues:

  • If @2x sync fails, verify the MediaCropModifiedEvent is dispatched (Sulu 3.x default).
  • Log: Enable debug:event-dispatcher to confirm event firing.

• Command Errors:

  • For image-formats:generate, ensure YAML is valid (use symfony/validator for testing).
  • Tip: Use --target=/tmp/test.xml to debug output before committing.

Extension Points

1. Custom Format Keys:

   • The bundle assumes @2x suffixes. To support other variants (e.g., @3x), extend the MediaCropModifiedSubscriber:

     // src/EventSubscriber/CustomCropSubscriber.php
     use Alengo\SuluMediaExtraBundle\EventSubscriber\MediaCropModifiedSubscriber;
     
     class CustomCropSubscriber extends MediaCropModifiedSubscriber {
         protected function getBaseFormatKey(string $formatKey): ?string {
             if (str_ends_with($formatKey, '@3x')) {
                 return str_replace('@3x', '', $formatKey);
             }
             return parent::getBaseFormatKey($formatKey);
         }
     }
     

   • Register the subscriber in services.yaml:

     Alengo\SuluMediaExtraBundle\EventSubscriber\MediaCropModifiedSubscriber:
         tags: [kernel.event_subscriber]
         arguments:
             $subscriber: '@custom_crop_subscriber'
     

2. Pre-Rename Validation:

   • Override the MediaRenameCommand to add custom logic (e.g., blacklist filenames):

     // src/Command/CustomMediaRenameCommand.php
     use Alengo\SuluMediaExtraBundle\Command\MediaRenameCommand;
     
     class CustomMediaRenameCommand extends MediaRenameCommand {
         protected function execute(InputInterface $input, OutputInterface $output): int {
             $newName = $input->getArgument('newName');
             if (str_contains($newName, 'blocked')) {
                 $output->writeln('<error>Filename blocked!</error>');
                 return Command::FAILURE;
             }
             return parent::execute($input, $output);
         }
     }
     

3. Storage Path Customization:

   • The rename command uses Sulu’s default storage adapter. To support custom paths (e.g., S3), extend the MediaRenamer service:

     // src/Service/CustomMediaRenamer.php
     use Alengo\SuluMediaExtraBundle\Service\MediaRenamer;
     
     class CustomMediaRenamer extends MediaRenamer {
         public function rename(Media $media, string $newName, string $locale): void {
             // Add custom logic (e.g., S3 path handling)
             parent::rename($media, $newName, $locale);
         }
     }
     

   • Override the service in services.yaml:

     Alengo\SuluMediaExtraBundle\Service\MediaRenamer:
         class: App\Service\CustomMediaRenamer