## Getting Started

### Minimal Setup
1. **Install Dependencies**:
   ```bash
   composer require artgris/media-bundle artgris/filemanager-bundle

Ensure artgris/filemanager-bundle is properly configured (see FileManagerBundle docs).

Register Bundle in config/bundles.php:

return [
    // ...
    Artgris\Bundle\MediaBundle\ArtgrisMediaBundle::class => ['all' => true],
];

Install Assets:
```
php bin/console assets:install
```
Include required assets (Bootstrap, jQuery, Font Awesome, etc.) in your base template (see README).

Configure Routing in config/routes.yaml:

artgris_media:
    resource: "@ArtgrisMediaBundle/Resources/config/routing.yml"
    prefix: /admin

First Use Case: Add a media field to an entity and form:

// src/Entity/Example.php
use Artgris\Bundle\MediaBundle\Form\Validator\Constraint as MediaAssert;

class Example {
    /**
     * @ORM\Column(type="string")
     * @MediaAssert\Image() // Optional: Validate as image
     */
    private $thumbnail;
}

// src/Form/ExampleType.php
use Artgris\Bundle\MediaBundle\Form\Type\MediaType;

$builder->add('thumbnail', MediaType::class, [
    'conf' => 'default', // Matches FileManager config
]);

Implementation Patterns

Common Workflows

Single Media Upload: Use MediaType for one-to-one file associations (e.g., profile pictures, thumbnails).

$builder->add('logo', MediaType::class, [
    'conf' => 'logos',
    'allow_crop' => true,
    'crop_options' => ['ratio' => '16/9'],
]);

Collections (Multiple Files): Use MediaCollectionType for galleries, documents, etc.

$builder->add('gallery', MediaCollectionType::class, [
    'conf' => 'images',
    'min' => 1,
    'max' => 10,
    'entry_options' => ['display_file_manager' => false], // Disable FM for entries
]);

Validation: Combine with Symfony’s @Assert or MediaAssert constraints:

use Artgris\Bundle\MediaBundle\Form\Validator\Constraint\Image;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @ORM\Column(type="string")
 * @Assert\NotBlank()
 * @Image(maxSize="2M") // Custom validation
 */
private $coverImage;

Dynamic Configurations: Pass extra parameters for FileManager-specific options (e.g., folder restrictions):

$builder->add('document', MediaType::class, [
    'conf' => 'documents',
    'extra' => ['folder' => 'user_uploads/{user_id}'],
]);

Read-Only Fields: Disable manual input for pre-populated media:

$builder->add('certificate', MediaType::class, [
    'conf' => 'certificates',
    'readonly' => true,
]);

Integration Tips

Doctrine Types: Use simple_array, array, or json for collections to preserve order.
Twig Templates: Access media URLs via entity.getMediaPath() or entity.getMediaUrl().
Asset Management: Override cropped paths in config/packages/artgris_media.yaml:
```
artgris_media:
    cropped_path: "uploads/cropped/"
```
Event Listeners: Extend functionality by subscribing to MediaUploadEvent or MediaDeleteEvent.

Gotchas and Tips

Pitfalls

Missing Dependencies:
- Forgetting artgris/filemanager-bundle or its configurations (e.g., filemanager YAML) will break media uploads.
- Fix: Verify FileManagerBundle is installed and configured with at least one conf (e.g., default).
Asset Loading:
- Failing to include all required assets (jQuery UI, jquery.collection.js, etc.) causes JS errors.
- Fix: Use the exact asset tags from the README.
Cropper Conflicts:
- If allow_crop: true is set but cropper.min.js/cropper.min.css are missing, the cropper UI won’t load.
- Fix: Ensure assets are installed and paths are correct in Twig templates.
Collection Order:
- Using json type for collections may lose order on save. Use simple_array instead.
- Fix: Update Doctrine type to simple_array in your entity.
Routing Conflicts:
- The bundle’s /admin prefix may clash with existing routes. Customize the prefix in routing.yml.
- Fix: Adjust the prefix in the routing import or use a unique path.
PHP Version:
- The bundle supports PHP 7.1+, but some features (e.g., PHP 8 attributes) require updates.
- Fix: Use composer require artgris/media-bundle:^6.1.1 for PHP 8 support.

Debugging Tips

Check Console Logs:
- Errors like 404 for JS/CSS files often indicate missing assets. Run:
```
php bin/console assets:install --symlink
```
FileManager Configs:
- If uploads fail, verify FileManagerBundle configs exist in config/packages/filemanager.yaml:
```
filemanager:
    dirs:
        default: "%kernel.project_dir%/public/uploads"
```
Cropper Debugging:
- Disable cropper temporarily to isolate issues:
```
'allow_crop' => false,
```

Event Debugging:

Listen for MediaUploadEvent to log upload paths:

// src/EventListener/MediaListener.php
public function onMediaUpload(MediaUploadEvent $event) {
    \Log::info('Uploaded file:', [$event->getFile()->getPathname()]);
}

services:
    App\EventListener\MediaListener:
        tags:
            - { name: kernel.event_listener, event: artgris_media.upload, method: onMediaUpload }

Extension Points

Custom Validators: Extend MediaAssert constraints or create new ones (e.g., for MIME types):

use Symfony\Component\Validator\Constraint;

class Video extends Constraint {
    public $message = 'This must be a video file.';
    // ...
}

Override Templates: Customize the file manager modal by overriding Twig templates in templates/bundles/artgrismedia/.

Add New File Types: Extend FileManagerBundle configs to support additional file types (e.g., PDFs, videos) via filemanager.yaml:

filemanager:
    dirs:
        videos:
            path: "%kernel.project_dir%/public/videos"
            allowed_mimes: ["video/mp4", "video/quicktime"]

Async Uploads: For large files, integrate with Symfony UX (e.g., ux-media-bundle) as suggested in the README.

Database Indexing: Add indexes to media columns in Doctrine for faster queries:

/**
 * @ORM\Column(type="string", length=255)
 * @ORM\Index(columns={"image"})
 */
private $image;

---

Media Bundle Laravel Package