mulertech/file-bundle

Symfony bundle for file upload management with metadata tracking, configurable validation, and extensible entity

v1.0.0 2026-04-04 21:53 UTC

Requires

• php: ^8.4
• doctrine/dbal: ^3.0 || ^4.0
• doctrine/orm: ^2.19 || ^3.0
• psr/log: ^3.0
• symfony/config: ^6.4 || ^7.0
• symfony/dependency-injection: ^6.4 || ^7.0
• symfony/http-foundation: ^6.4 || ^7.0
• symfony/http-kernel: ^6.4 || ^7.0
• symfony/mime: ^6.4 || ^7.0
• symfony/string: ^6.4 || ^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• mulertech/docker-dev: ^3.2
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0
• roave/security-advisories: dev-latest
• twig/twig: ^3.0

Suggests

• twig/twig: Required to use the file_exists_on_disk() and format_file_size() Twig functions

MIT

• Sébastien Muler

• symfony
• php
• metadata
• file
• storage
• upload
• file-management

README

Symfony bundle for file upload management with metadata tracking, configurable validation, and an extensible entity.

Requirements

• PHP 8.4+
• Symfony 6.4+ or 7.0+
• Doctrine ORM 2.19+ or 3.0+

Installation

composer require mulertech/file-bundle

Configuration

# config/packages/mulertech_file.yaml
mulertech_file:
    storage_directory: '%kernel.project_dir%/var/documents'
    file_class: App\Entity\File
    # max_file_size: 52428800  # 50MB (default)
    # directory_strategy: null  # Service ID for custom DirectoryStrategyInterface
    # allowed_mime_types:       # Override default MIME types
    #     - 'application/pdf'
    #     - 'image/jpeg'

Usage

1. Create your File entity

Extend the provided AbstractFile MappedSuperclass:

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use MulerTech\FileBundle\Entity\AbstractFile;

#[ORM\Entity]
#[ORM\Table(name: 'files')]
class File extends AbstractFile
{
    #[ORM\ManyToOne]
    #[ORM\JoinColumn(nullable: false)]
    private User $uploadedBy;

    // Add your own relations and fields...
}

2. Implement FileUploaderInterface

Your User entity must implement FileUploaderInterface:

use MulerTech\FileBundle\Model\FileUploaderInterface;

class User implements FileUploaderInterface
{
    public function getId(): ?int { /* ... */ }
}

3. Upload files

Inject FileManagerInterface in your controller or service:

use MulerTech\FileBundle\Service\FileManagerInterface;

class FileController
{
    public function upload(FileManagerInterface $fileManager, Request $request): Response
    {
        $uploadedFile = $request->files->get('file');
        $file = $fileManager->upload($uploadedFile, $user);

        // $file is your concrete entity, persisted and flushed
    }
}

4. Custom directory strategy (optional)

Implement DirectoryStrategyInterface to control where files are stored:

use MulerTech\FileBundle\Storage\DirectoryStrategyInterface;
use MulerTech\FileBundle\Model\FileUploaderInterface;

class ProjectDirectoryStrategy implements DirectoryStrategyInterface
{
    public function getRelativeDirectory(FileUploaderInterface $uploader, ?object $context = null): string
    {
        if ($context instanceof Project) {
            return sprintf('project_%d', $context->getId());
        }

        return sprintf('user_%d', $uploader->getId());
    }
}

Then configure:

mulertech_file:
    directory_strategy: App\Storage\ProjectDirectoryStrategy

5. Twig functions

{% if file_exists_on_disk(file) %}
    <span>{{ format_file_size(file.size) }}</span>
{% endif %}

Testing

./vendor/bin/mtdocker test-ai

License

MIT