Ux Media Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require arkounay/ux-media
   npm install --force && npm run watch
   

   Ensure StimulusBundle is configured in your app.

2. Routing: Add routes in config/routes.yaml:

   artgris_file_manager:
       resource: "@ArtgrisFileManagerBundle/Controller"
       type: attribute
       prefix: /admin/manager
   
   ux_media:
       resource: "@ArkounayUxMediaBundle/Controller"
       type: attribute
       prefix: /admin/ux-media
   

3. Configuration: Define artgris_file_manager config in packages/artgris_file_manager.yaml:

   artgris_file_manager:
       conf:
           default:
               dir: '%kernel.project_dir%/public/uploads'
   

4. First Use Case: Replace MediaType with UxMediaType in your form builder:

   $builder->add('media', UxMediaType::class, [
       'conf' => 'default',
       'tree' => true,
       'display_file_manager' => true,
   ]);
   

Implementation Patterns

Form Integration

• Basic Usage: Use UxMediaType for single media uploads and UxMediaCollectionType for collections:

  $builder->add('media', UxMediaCollectionType::class, [
      'conf' => 'default',
      'allow_add' => true,
      'allow_delete' => true,
      'by_reference' => false,
  ]);
  

• Crop Options: Enable cropping with customizable options:

  $builder->add('media', UxMediaType::class, [
      'allow_crop' => true,
      'crop_options' => [
          'display_crop_data' => true,
          'allow_flip' => true,
          'allow_rotation' => true,
      ],
  ]);
  

• EasyAdmin Integration: Override configureCrud to include form themes:

  public function configureCrud(): Crud {
      return Crud::new()
          ->addFormTheme('@ArkounayUxMedia/ux_media_form_theme.html.twig');
  }
  

Asset Management

• Webpack Encore: Ensure ux-media controllers are enabled in webpack.config.js:

  Encore.enableSassLoader();
  Encore.autoProvidejQuery();
  

• AssetMapper: No additional config required beyond composer require and routing.

Validation

• Image Validation: Use ImageValidator for image-specific rules (e.g., dimensions, formats):

  $builder->add('media', UxMediaType::class, [
      'constraints' => [
          new ImageValidator(['minWidth' => 100, 'minHeight' => 100]),
      ],
  ]);
  

Gotchas and Tips

Common Pitfalls

1. Missing Routes: Forgetting to add ux_media or artgris_file_manager routes will break the file manager UI. Fix: Verify config/routes.yaml includes both routes.

2. Bootstrap Dependency: The package requires Bootstrap 5. If using a custom UI, enable bootstrap_modal in webpack.config.js:

   controllers: {
       "@arkounay/ux-media": {
           "bootstrap_modal": { "enabled": true }
       }
   }
   

3. StimulusBundle: Ensure StimulusBundle is installed and configured. Without it, async uploads won’t work. Fix: Run composer require symfony/stimulus-bundle.

4. CropperJS Conflicts: If crop functionality fails, check for duplicate CropperJS instances or missing CSS imports. Fix: Verify cropperjs/dist/cropper.min.css is imported in webpack.config.js.

5. Twig Deprecations: The package uses spaceless filter, which is deprecated in Twig 3.12+. Update your Twig templates to use alternatives like |striptags.

Debugging Tips

• Console Errors: Check browser console for Stimulus or CropperJS errors. Common issues include:

  • Missing data-controller attributes on form fields.
  • Failed asset compilation (run npm run watch or yarn watch).

• File Permissions: Ensure the upload directory (%kernel.project_dir%/public/uploads) is writable:

  chmod -R 775 public/uploads
  

• Network Requests: Use browser dev tools to inspect failed API calls to /admin/ux-media or /admin/manager. Verify CORS headers if using a separate frontend.

Extension Points

1. Custom Templates: Override Twig templates (e.g., @ArkounayUxMedia/ux_media_widget.html.twig) to modify UI behavior.

2. Validation Rules: Extend ImageValidator or create custom constraints for business logic:

   use Arkounay\UxMediaBundle\Validator\Constraints\ImageValidator;
   

3. File Manager Config: Extend artgris_file_manager config to support additional storage backends (e.g., S3):

   artgris_file_manager:
       conf:
           s3:
               adapter: 'aws'
               bucket: 'your-bucket'
               region: 'us-east-1'
   

4. Stimulus Controllers: Customize Stimulus controllers (e.g., ux-media-upload) by extending the package’s JS classes:

   // assets/controllers/ux_media_upload_controller.js
   import { UxMediaUploadController } from '@arkounay/ux-media';
   export default class extends UxMediaUploadController {
       connect() {
           super.connect();
           console.log('Custom upload logic');
       }
   }
   

Performance

• Lazy Loading: Use fetch: "eager" sparingly for critical assets. Prefer lazy-loading for non-critical components:

  controllers: {
      "@arkounay/ux-media": {
          "upload": { "fetch": "lazy" }
      }
  }
  

• Image Optimization: Enable webp support (built-in since v4.1.0) to reduce file sizes:

  $builder->add('media', UxMediaType::class, [
      'allowed_extensions' => ['jpg', 'png', 'webp'],
  ]);
  

EasyAdmin-Specific

• Asset Configuration: Ensure configureAssets includes Webpack Encore:

  public function configureAssets(Assets $assets): Assets {
      return $assets->addWebpackEncoreEntry('app');
  }
  

• Form Themes: Always include both ux_collection and ux_media form themes in configureCrud:

  ->addFormTheme('@ArkounayUxCollection/ux_collection_form_theme.html.twig')
  ->addFormTheme('@ArkounayUxMedia/ux_media_form_theme.html.twig')
  

Migration Notes

• Symfony 8+: The package supports Symfony 8, but test thoroughly for Stimulus/UX compatibility.
• AssetMapper: No breaking changes, but ensure AssetMapper is configured if migrating from Webpack Encore.