mulertech / file-bundle
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
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 || ^8.0
- symfony/dependency-injection: ^6.4 || ^7.0 || ^8.0
- symfony/http-foundation: ^6.4 || ^7.0 || ^8.0
- symfony/http-kernel: ^6.4 || ^7.0 || ^8.0
- symfony/mime: ^6.4 || ^7.0 || ^8.0
- symfony/string: ^6.4 || ^7.0 || ^8.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
Provides
None
Conflicts
None
Replaces
None
README
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'supload_max_filesize) or of a type not allowed. The sender can fix it by sending another file, so tell them why.reason(FileRejectionReason::TooLargeorTypeNotAllowed),filename,maxSize(bytes) andmimeTypelet 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 aterrorlevel 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