Getting Started

Minimal Setup

Installation:

composer require silasjoisten/sonata-multiupload-bundle

Enable the bundle in config/bundles.php:

Silasjoisten\SonataMultiuploadBundle\SonataMultiuploadBundle::class => ['all' => true],

Configuration: Add the bundle to your Sonata Admin configuration:

# config/packages/sonata_multiupload.yaml
sonata_multiupload:
    enabled: true
    max_file_size: 10M  # Default max file size
    allowed_mime_types: ['image/jpeg', 'image/png']  # Restrict file types

First Use Case: Extend a Sonata Admin class to enable multi-upload for a field:

use Silasjoisten\SonataMultiuploadBundle\Admin\Type\MultiuploadType;

protected function configureFormFields(FormMapper $formMapper)
{
    $formMapper
        ->add('images', 'sonata_multiupload', [
            'label' => 'Images',
            'required' => false,
            'multiple' => true,
            'btn_text' => 'Upload Images',
            'btn_icon' => 'fa fa-upload',
        ]);
}

Frontend Setup: Ensure you include the bundle's JS/CSS in your base template:
```
{{ sonata_multiupload_js() }}
{{ sonata_multiupload_css() }}
```

Implementation Patterns

Common Workflows

1. Basic Multi-File Upload

Use the sonata_multiupload field type in Sonata Admin forms.

Example for a ProductAdmin:

$formMapper->add('gallery', 'sonata_multiupload', [
    'label' => 'Gallery Images',
    'multiple' => true,
    'btn_text' => 'Add to Gallery',
    'preview_size' => [100, 100], // Thumbnail size
]);

2. Handling Uploaded Files

Override the prePersist() or preUpdate() methods to process uploaded files:

public function prePersist($object)
{
    if ($object->getGallery()) {
        foreach ($object->getGallery() as $file) {
            // Save file logic (e.g., move to storage, generate thumbnails)
        }
    }
}

3. Dynamic Configuration

Use dependency injection to dynamically configure the upload field:

$formMapper->add('documents', 'sonata_multiupload', [
    'label' => 'Documents',
    'allowed_mime_types' => $this->getConfigurationPool()->getContainer()->getParameter('sonata_multiupload.allowed_doc_types'),
]);

4. Integration with Sonata Media Bundle

If using sonata-media-bundle, configure the field to work with media entities:

$formMapper->add('media', 'sonata_multiupload', [
    'label' => 'Media',
    'media_provider' => 'sonata.media.provider.file', // Specify provider
    'context' => 'product_gallery', // Media context
]);

5. Custom Validation

Add validation rules via the field options:

$formMapper->add('attachments', 'sonata_multiupload', [
    'constraints' => [
        new \Symfony\Component\Validator\Constraints\File([
            'maxSize' => '5M',
            'mimeTypes' => ['application/pdf'],
            'mimeTypesMessage' => 'Only PDF files are allowed',
        ]),
    ],
]);

6. Batch Processing

Process uploaded files in bulk after form submission:

public function postUpdate($object, FormInterface $form, Request $request)
{
    $data = $form->getData();
    if (isset($data['attachments'])) {
        $this->processAttachments($data['attachments']);
    }
}

Integration Tips

Sonata Admin CRUD

Ensure the bundle is loaded after SonataAdminBundle in config/bundles.php.
Clear cache after enabling the bundle:
```
php bin/console cache:clear
```

Frontend Customization

Override the default template by copying: vendor/silasjoisten/sonata-multiupload-bundle/Resources/views/sonata_multiupload/_form_field.html.twig to your theme’s templates/sonata_multiupload/ directory.

API/REST Integration

For API endpoints, use the sonata_multiupload field in API platforms:

# config/packages/api_platform.yaml
api_platform:
    formats:
        jsonld:
            mime_types: ['application/ld+json']
        json:
            mime_types: ['application/json', 'application/vnd.api+json']
    resources:
        - { type: App\Entity\Product, operations: { collection: { method: 'POST', deserialization_context: { groups: ['upload'] } } } }

Event Listeners

Listen for upload events to log or process files:

// src/EventListener/MultiuploadListener.php
public function onMultiuploadUpload(KernelEvents::VIEW, GetResponseEvent $event)
{
    $request = $event->getRequest();
    if ($request->isXmlHttpRequest() && $request->query->has('sonata_multiupload')) {
        // Handle upload logic
    }
}

Gotchas and Tips

Pitfalls

1. File Size Limits

Issue: Uploads fail silently if files exceed php.ini limits (upload_max_filesize, post_max_size).

Fix: Adjust server settings or validate files client-side:

// In your custom JS
$('#sonata-multiupload').fileupload({
    maxFileSize: 10000000, // 10MB
    acceptFileTypes: /(\.|\/)(gif|jpe?g|png)$/i,
});

2. CSRF Token Mismatch

Issue: AJAX uploads may fail with "CSRF token not found" if the token isn’t included.

Fix: Ensure the token is embedded in the upload request:

$.ajaxSetup({
    headers: {
        'X-CSRF-Token': $('meta[name="csrf-token"]').attr('content')
    }
});

3. Missing JavaScript Dependencies

Issue: Upload UI fails to load if jQuery or Bootstrap are missing.

Fix: Verify dependencies in assets/app.js:

//= require jquery
//= require bootstrap
//= require sonata-multiupload

4. Permission Denied on File Storage

Issue: Uploaded files aren’t saved to the target directory due to permissions.
Fix: Ensure the uploads/ directory is writable:
```
chmod -R 775 var/uploads
```

5. Conflicts with Other Upload Bundles

Issue: Conflicts with stof/doctrine-extensions or vich/uploader-bundle.

Fix: Disable other upload handlers or merge configurations:

sonata_multiupload:
    enabled: true
    upload_handler: sonata_multiupload.handler.file # Override default

6. Template Not Found

Issue: Twig throws TemplateNotFoundException for sonata_multiupload/_form_field.html.twig.

Fix: Copy the template from the vendor directory to your theme:

mkdir -p templates/sonata_multiupload
cp vendor/silasjoisten/sonata-multiupload-bundle/Resources/views/sonata_multiupload/_form_field.html.twig templates/sonata_multiupload/

Debugging Tips

1. Enable Debug Mode

Set APP_DEBUG=true in .env to log upload errors:
```
APP_DEBUG=1
```

2. Check Browser Console

Look for 403/500 errors in the Network tab during uploads.

3. Log Upload Events

Add a listener to log upload data:

public function onKernelRequest(GetResponseEvent $event)
{
    $request = $event->getRequest();
    if ($request->query->has('sonata_multiupload')) {
        \Log::debug('Multiupload request:', $request->query->all());
    }
}

4. Validate File Paths

Ensure sonata_multiupload.upload_dir in config points to a valid, writ

Sonata Multiupload Bundle Laravel Package