檔案

編輯此頁面

驗證值是否為有效的「檔案」，可以是下列其中一種

字串（或具有 __toString() 方法的物件），指向現有檔案的路徑；
有效的 File 物件（包括 UploadedFile 類別的物件）。

此限制條件通常用於表單中，搭配 FileType 表單欄位使用。

另請參閱

如果您要驗證的檔案是圖片，請嘗試 Image 限制條件。

適用於	屬性或方法
類別	檔案
驗證器	FileValidator

基本用法

此限制條件最常用於屬性上，該屬性將在表單中呈現為 FileType 欄位。例如，假設您正在建立作者表單，您可以在其中為作者上傳「簡歷」PDF 檔案。在您的表單中，bioFile 屬性將為 file 類型。Author 類別可能如下所示

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // src/Entity/Author.php
namespace App\Entity;

use Symfony\Component\HttpFoundation\File\File;

class Author
{
    protected File $bioFile;

    public function setBioFile(?File $file = null): void
    {
        $this->bioFile = $file;
    }

    public function getBioFile(): File
    {
        return $this->bioFile;
    }
}
    

為了確保 bioFile File 物件有效，且檔案大小低於特定值，並且是有效的 PDF 檔案，請新增以下內容

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // src/Entity/Author.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\File(
        maxSize: '1024k',
        extensions: ['pdf'],
        extensionsMessage: 'Please upload a valid PDF',
    )]
    protected File $bioFile;
}
    

        1
2
3
4
5
6
7
8
        # config/validator/validation.yaml
App\Entity\Author:
    properties:
        bioFile:
            - File:
                maxSize: 1024k
                extensions: [pdf]
                extensionsMessage: Please upload a valid PDF
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="https://symfony.dev.org.tw/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://symfony.dev.org.tw/schema/dic/constraint-mapping https://symfony.dev.org.tw/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="App\Entity\Author">
        <property name="bioFile">
            <constraint name="File">
                <option name="maxSize">1024k</option>
                <option name="extensions">
                    <value>pdf</value>
                </option>
                <option name="extensionsMessage">Please upload a valid PDF</option>
            </constraint>
        </property>
    </class>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        // src/Entity/Author.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;

class Author
{
    // ...

    public static function loadValidatorMetadata(ClassMetadata $metadata): void
    {
        $metadata->addPropertyConstraint('bioFile', new Assert\File([
            'maxSize' => '1024k',
            'extensions' => [
                'pdf',
            ],
            'extensionsMessage' => 'Please upload a valid PDF',
        ]));
    }
}
    

bioFile 屬性經過驗證，以確保它是一個真實的檔案。其大小和 mime 類型也經過驗證，因為已指定適當的選項。

注意

與大多數其他限制條件一樣，null 和空字串被視為有效值。這是為了允許它們成為可選值。如果該值是強制性的，常見的解決方案是將此限制條件與 NotBlank 結合使用。

選項

`binaryFormat`

類型：boolean 預設值：null

當為 true 時，大小將在訊息中以二進位字首單位 (KiB、MiB) 顯示。當為 false 時，大小將以 SI 字首單位 (kB、MB) 顯示。當為 null 時，binaryFormat 將從 maxSize 選項中定義的值推測而來。

有關二進位和 SI 字首之間差異的更多資訊，請參閱 Wikipedia：二進位字首。

`extensions`

類型：array 或 string

如果設定，驗證器將檢查基礎檔案的副檔名和媒體類型（以前稱為 MIME 類型）是否等於給定的副檔名和相關的媒體類型（如果是字串），或是否存在於集合中（如果是陣列）。

預設情況下，允許所有與副檔名相關聯的媒體類型。支援的副檔名和相關媒體類型的列表可以在 IANA 網站上找到。

也可以明確地為副檔名配置授權的媒體類型。

在以下範例中，允許的媒體類型已針對 xml 和 txt 副檔名明確設定，並且允許 jpg 的所有相關聯媒體類型

        1
2
3
4
5
        [
    'xml' => ['text/xml', 'application/xml'],
    'txt' => 'text/plain',
    'jpg',
]
    

`disallowEmptyMessage`

類型：string 預設值：不允許空檔案。

此限制條件檢查上傳的檔案是否為空（即 0 位元組）。如果是，則會顯示此訊息。

您可以在此訊息中使用以下參數

參數	描述
`{{ file }}`	絕對檔案路徑
`{{ name }}`	基礎檔案名稱

`groups`

類型：array | string 預設值：null

它定義此限制條件的驗證群組。閱讀更多關於驗證群組的資訊。

`maxSize`

類型：mixed

如果設定，為了使其有效，基礎檔案的大小必須低於此檔案大小。檔案大小可以用以下格式之一給定

後綴	單位名稱	值	範例
(無)	位元組	1 位元組	`4096`
`k`	千位元組	1,000 位元組	`200k`
`M`	百萬位元組	1,000,000 位元組	`2M`
`Ki`	千位元組 (二進位)	1,024 位元組	`32Ki`
`Mi`	百萬位元組 (二進位)	1,048,576 位元組	`8Mi`

有關二進位和 SI 字首之間差異的更多資訊，請參閱 Wikipedia：二進位字首。

`maxSizeMessage`

類型：string 預設值：檔案太大 ({{ size }} {{ suffix }})。允許的最大大小為 {{ limit }} {{ suffix }}.

如果檔案大於 maxSize 選項，則顯示的訊息。

您可以在此訊息中使用以下參數

參數	描述
`{{ file }}`	絕對檔案路徑
`{{ limit }}`	允許的最大檔案大小
`{{ name }}`	基礎檔案名稱
`{{ size }}`	給定檔案的檔案大小
`{{ suffix }}`	使用的檔案大小單位的後綴（請參閱上文）