Symfony News

New in Symfony 6.2: Improved File Validator

Contributed by
Kévin Dunglas
in #47710.

The File constraint from the Validator component checks that a given value is a valid file. One of its options is called mimeTypes and it verifies that the media type (formerly known as MIME type) of the file is one of the given values:

use Symfony\Component\Validator\Constraints as Assert;

class ScannedDocument
{
    #[Assert\File(
        maxSize: '1024k',
        mimeTypes: ['application/pdf', 'application/x-pdf'],
    )]
    protected $pdfFile;

    // ...
}

The values passed to mimeTypes must be any of the official list of valid media types. Some of these values are confusing and cumbersome even for common file types (e.g. Microsoft Excel have multiple media types associated to it, such as application/vnd.ms-excel, application/vnd.ms-excel.sheet.macroEnabled.12, etc.)

In Symfony 6.2 we're improving the File constraint with a new option called extensions. This option checks both the file extension and its media type. Using this option, the above example looks as follows:

use Symfony\Component\Validator\Constraints as Assert;

class ScannedDocument
{
    #[Assert\File(maxSize: '1024k', extensions: 'pdf')]
    protected $pdfFile;

    // ...
}

The extensions option checks both that the file has exactly the .pdf extension and that its media type is any of the types associated to that extension in the official list (application/pdf, application/x-pdf, etc.)

In the following example, we allow uploading any file associated to JPEG media types, but require that the extension is .jpg (so, .jpeg files won't be allowed):

use Symfony\Component\Validator\Constraints as Assert;

class UserProfile
{
    #[Assert\File(maxSize: '250k', extensions: 'jpg')]
    protected $avatar;

    // ...
}

The extensions option also allows to pass a list of media types to accept for the extension. Moreover, you can pass an array to accept several extensions, each of them optionally defining which media types to accept:

use Symfony\Component\Validator\Constraints as Assert;

class SharedFile
{
    #[Assert\File(extensions: [
        'jpg',
        'txt' => 'text/plain',
        'xml' => ['text/xml', 'application/xml'],
    ])]
    protected $contents;

    // ...
}