Search by

mulertech / file-bundle

mulertech

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

Package info

github.com/mulertech/file-bundle

Type:symfony-bundle

pkg:composer/mulertech/file-bundle

Statistics

Installs: 646

Dependents: 1

Suggesters: 0

Stars: 0

Open Issues: 0

v2.0.0 2026-11-19 18:33 UTC

This package is auto-updated.

Last update: 2026-11-19 18:50:31 UTC


README

Latest Version on Packagist GitHub Tests Action Status GitHub PHPStan Action Status Total Downloads Test Coverage

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

Requirements

  • PHP 8.4+
  • Symfony 6.4+, 7.0+ or 8.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
    }
}

upload() throws two kinds of FileException, which call for different answers:

  • MulerTech\FileBundle\Exception\FileRejected: the file is too large (for the bundle or for PHP's upload_max_filesize) or of a type not allowed. The sender can fix it by sending another file, so tell them why. reason (FileRejectionReason::TooLarge or TypeNotAllowed), filename, maxSize (bytes) and mimeType let you write that message in your own language.
  • any other FileException: the server failed to receive or store the file. Nothing the sender does will fix it, so report it as an error. Its message names the cause (the file, the path) and the bundle journals nothing at error level itself: the caller is the one place that reports it, so a fault raises one alert, not one per layer.
use MulerTech\FileBundle\Exception\FileRejected;
use Symfony\Component\HttpFoundation\File\Exception\FileException;

try {
    $file = $fileManager->upload($uploadedFile, $user);
} catch (FileRejected $rejected) {
    // show the reason to the sender
} catch (FileException $failure) {
    $logger->error('File upload failed', ['exception' => $failure]);
}

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. Storage target (for bundles)

A bundle storing files that must be laid out the same way on every site passes as context an object implementing StorageTargetInterface. It gives the directory and the start of the stored name itself, and the site's directory strategy is not consulted:

use MulerTech\FileBundle\Storage\StorageTargetInterface;

final readonly class CoverTarget implements StorageTargetInterface
{
    public function __construct(private int $postId)
    {
    }

    public function getRelativeDirectory(): string
    {
        return 'blog/images';
    }

    public function getFilenamePrefix(): string
    {
        return sprintf('image-%d-', $this->postId);
    }
}

$file = $fileManager->upload($uploadedFile, $user, new CoverTarget($post->getId()), true);
// blog/images/image-12-6650c1f2a3b4e1.23456789.webp

The unique part and the extension follow the prefix. The directory is made of segments of letters, digits, _ and - joined by /, the prefix of the same characters without /; anything else (.., an absolute path) is refused with an InvalidArgumentException naming the target, since it would write outside the storage directory.

The uploader is not stored on the file: it only feeds the directory strategy and the upload log. Deleting a user deletes none of their files, unless the site's own file entity links the two with a cascade.

6. Twig functions

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

Testing

./vendor/bin/mtdocker test-ai

License

MIT