Getting Started

Minimal Steps

Installation:
```
composer require christmann/pluploadbundle:dev-Symfony2.3
```
Replace dev-Symfony2.3 with dev-Symfony2.2 or dev-master for older Symfony versions.
Enable the Bundle: Add new CIM\PluploadBundle\CIMPluploadBundle() to app/AppKernel.php under registerBundles().

First Use Case: Create a form type with the plupload field:

// src/Acme/DemoBundle/Form/DemoType.php
use CIM\PluploadBundle\Form\Type\PluploadType;

public function buildForm(FormBuilderInterface $builder, array $options) {
    $builder->add('files', PluploadType::class, [
        'label' => 'Upload Files',
        'allowed_mime_types' => ['image/jpeg', 'image/png'],
        'max_file_count' => 5,
    ]);
}

Ensure you have a route and controller to handle the form submission.

Twig Integration: Include the bundle’s assets in your base template:

{% block stylesheets %}
    {{ parent() }}
    {{ cim_plupload_assets() }}
{% endblock %}

Implementation Patterns

Core Workflows

Basic File Upload: Use the plupload form type with minimal configuration:
```
$builder->add('files', PluploadType::class, [
    'label' => 'Upload',
    'max_file_size' => '10MB', // e.g., '10MB', '500KB'
]);
```
- Twig Rendering: The field renders a drag-and-drop upload zone with progress bars.
- Validation: Validate files server-side using Symfony’s validators (e.g., File constraint).
Chunked Uploads: Enable chunked uploads for large files:
```
$builder->add('files', PluploadType::class, [
    'chunk_size' => '1MB',
    'max_chunks' => 10,
]);
```
- Handler: Configure a custom upload handler (see CIM\PluploadBundle\Handler\UploadHandler) to manage chunks.

Dynamic Configuration: Pass runtime options via options:

$builder->add('files', PluploadType::class, [
    'runtime_config' => [
        'multipart' => true, // Enable multipart uploads
        'url' => $this->generateUrl('upload_endpoint'),
    ],
]);

Integration with VichUploaderBundle: Combine with VichUploaderBundle for persistent file storage:

use Vich\UploaderBundle\Form\Type\VichFileType;

$builder->add('file', VichFileType::class, [
    'image_upload_destination' => 'uploads',
    'asset' => 'file', // Field name in entity
    'download_uri' => true,
]);

Note: Use plupload for the upload UI and VichFileType for entity mapping.

Custom Templates: Override the default Twig templates:

{# templates/CIMPlupload/plupload_widget.html.twig #}
{% extends 'CIMPluploadBundle::plupload_widget.html.twig' %}
{% block plupload_container %}
    <div class="custom-upload-zone">
        {{ parent() }}
    </div>
{% endblock %}

Gotchas and Tips

Pitfalls

Symfony Version Compatibility:
- The bundle is abandoned and lacks support for Symfony 3.4+/4.x/5.x.
- Workaround: Fork the repo and update dependencies (e.g., symfony/form, twig) manually.
- Alternative: Use stof/doctrine-extensions + custom Plupload integration for modern Symfony.

Chunked Upload Handling:

The default UploadHandler does not persist chunks to disk. Implement a custom handler:

// src/Acme/DemoBundle/Handler/CustomUploadHandler.php
use CIM\PluploadBundle\Handler\UploadHandler;

class CustomUploadHandler extends UploadHandler {
    protected function handleChunk($chunk) {
        $path = $this->getUniquePath();
        file_put_contents($path, $chunk['data']);
        return $path;
    }
}

services:
    acme.demo.handler.upload:
        class: Acme\DemoBundle\Handler\CustomUploadHandler
        tags: ['plupload.handler']

CSRF Protection:
- Plupload lacks built-in CSRF protection. Add a hidden field to your form:
```
{{ form_hidden(form._token) }}
```
- Or use Symfony’s csrf_token in JavaScript:
```
var token = '{{ csrf_token('plupload_upload') }}';
```
File Validation:
- Client-side validation (e.g., allowed_mime_types) is not enforced server-side by default.
- Add validation in your controller:
```
$file = $request->files->get('files');
if (!$file->isValid()) {
    throw $this->createNotFoundException('Invalid file');
}
```
Asset Loading:
- The cim_plupload_assets() Twig function may fail if assets aren’t published.
- Fix: Manually copy assets from vendor/CIM/PluploadBundle/Resources/public to web/bundles/cimplupload.

Debugging Tips

Check JavaScript Errors:
- Open browser console (F12) to verify Plupload initialization:
```
console.log(plupload); // Should show Plupload object
```
- Common issues: Missing jQuery or plupload.full.js.
Server Logs:
- Enable debug mode (APP_DEBUG=true) to log upload errors.
- Check php_error.log for file permission issues.
Network Tab:
- Inspect XHR requests in the Network tab to verify:
  - Chunks are uploaded correctly.
  - Server responses include 200 OK (not 403 Forbidden or 500).

Extension Points

Custom Upload URL: Override the upload endpoint dynamically:

$builder->add('files', PluploadType::class, [
    'runtime_config' => [
        'url' => $this->generateUrl('dynamic_upload_route', ['id' => $entity->getId()]),
    ],
]);

Event Listeners: Subscribe to Plupload events (e.g., FileUploadedEvent):

// src/Acme/DemoBundle/EventListener/UploadListener.php
use CIM\PluploadBundle\Event\FileUploadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class UploadListener implements EventSubscriberInterface {
    public static function getSubscribedEvents() {
        return [
            'plupload.file_uploaded' => 'onFileUploaded',
        ];
    }

    public function onFileUploaded(FileUploadedEvent $event) {
        $file = $event->getFile();
        // Process file (e.g., store metadata)
    }
}

Plupload Configuration: Extend Plupload’s runtime settings:

$builder->add('files', PluploadType::class, [
    'runtime_config' => [
        'filters' => [
            { 'title': 'Image files', 'extensions': 'jpg,gif,png' },
        ],
        'resize' => ['width': 320, 'height': 240, 'quality': 90],
    ],
]);

Performance

Disable Multipart for small files to reduce overhead:
```
'runtime_config' => ['multipart': false],
```

Use run_time to limit upload timeouts:

'runtime_config' => ['run_time': 300], // 5 minutes

Pluploadbundle Laravel Package