圖片

編輯此頁面

Image 約束條件的功能與 File 約束條件完全相同，差別在於它的 mimeTypes 和 mimeTypesMessage 選項會自動設定為專門用於圖片檔案。

此外，它還提供選項，讓您可以根據圖片的寬度和高度進行驗證。

關於此約束條件的大部分文件，請參閱 File 約束條件。

適用於	屬性或方法
類別	圖片
驗證器	ImageValidator

基本用法

此約束條件最常用於將在表單中呈現為 FileType 欄位的屬性。例如，假設您正在建立作者表單，您可以在其中為作者上傳「大頭照」圖片。在您的表單中，headshot 屬性將會是 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 $headshot;

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

    public function getHeadshot(): File
    {
        return $this->headshot;
    }
}
    

為了確保 headshot File 物件是有效的圖片，並且尺寸介於特定範圍之間，請新增以下內容

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

use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\Image(
        minWidth: 200,
        maxWidth: 400,
        minHeight: 200,
        maxHeight: 400,
    )]
    protected File $headshot;
}
    

        1
2
3
4
5
6
7
8
9
        # config/validator/validation.yaml
App\Entity\Author:
    properties:
        headshot:
            - Image:
                minWidth: 200
                maxWidth: 400
                minHeight: 200
                maxHeight: 400
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- 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="headshot">
            <constraint name="Image">
                <option name="minWidth">200</option>
                <option name="maxWidth">400</option>
                <option name="minHeight">200</option>
                <option name="maxHeight">400</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
        // 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('headshot', new Assert\Image([
            'minWidth' => 200,
            'maxWidth' => 400,
            'minHeight' => 200,
            'maxHeight' => 400,
        ]));
    }
}
    

headshot 屬性經過驗證，以確保它是一個真正的圖片，並且寬度和高度都在特定範圍內。

您可能還希望確保 headshot 圖片是正方形。在這種情況下，您可以停用縱向和橫向方向，如下列程式碼所示

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

use Symfony\Component\HttpFoundation\File\File;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\Image(
        allowLandscape: false,
        allowPortrait: false,
    )]
    protected File $headshot;
}
    

        1
2
3
4
5
6
7
        # config/validator/validation.yaml
App\Entity\Author:
    properties:
        headshot:
            - Image:
                allowLandscape: false
                allowPortrait: false
    

        1
2
3
4
5
6
7
8
9
        <!-- config/validator/validation.xml -->
<class name="App\Entity\Author">
    <property name="headshot">
        <constraint name="Image">
            <option name="allowLandscape">false</option>
            <option name="allowPortrait">false</option>
        </constraint>
    </property>
</class>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // 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('headshot', new Assert\Image([
            'allowLandscape' => false,
            'allowPortrait' => false,
        ]));
    }
}
    

您可以混合所有約束條件選項，以建立強大的驗證規則。

選項

此約束條件與 File 約束條件共用所有選項。但是，它修改了兩個預設選項值，並新增了幾個其他選項。

`allowLandscape`

類型： Boolean 預設值： true

如果此選項為 false，則圖片不能為橫向。

注意

此選項不適用於 SVG 檔案。如果您將其與 SVG 檔案一起使用，您將會看到 sizeNotDetectedMessage 選項中定義的錯誤訊息。

`allowLandscapeMessage`

類型： string 預設值： 圖片為橫向 ({{ width }}x{{ height }}px)。不允許橫向圖片

如果圖片為橫向，並且您將 allowLandscape 設定為 false 時，會顯示此錯誤訊息。

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

參數	描述
`{{ height }}`	目前高度
`{{ width }}`	目前寬度

`allowPortrait`

類型： Boolean 預設值： true

如果此選項為 false，則圖片不能為縱向。

注意

此選項不適用於 SVG 檔案。如果您將其與 SVG 檔案一起使用，您將會看到 sizeNotDetectedMessage 選項中定義的錯誤訊息。

`allowPortraitMessage`

類型： string 預設值： 圖片為縱向 ({{ width }}x{{ height }}px)。不允許縱向圖片

如果圖片為縱向，並且您將 allowPortrait 設定為 false 時，會顯示此錯誤訊息。

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

參數	描述
`{{ height }}`	目前高度
`{{ width }}`	目前寬度

`allowSquare`

類型： Boolean 預設值： true

如果此選項為 false，則圖片不能為正方形。如果您想要強制圖片為正方形，請將此選項保留為預設值 true，並將 allowLandscape 和 allowPortrait 都設定為 false。

注意

此選項不適用於 SVG 檔案。如果您將其與 SVG 檔案一起使用，您將會看到 sizeNotDetectedMessage 選項中定義的錯誤訊息。

`allowSquareMessage`

類型： string 預設值： 圖片為正方形 ({{ width }}x{{ height }}px)。不允許正方形圖片

如果圖片為正方形，並且您將 allowSquare 設定為 false 時，會顯示此錯誤訊息。

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

參數	描述
`{{ height }}`	目前高度
`{{ width }}`	目前寬度

`corruptedMessage`

類型： string 預設值： 圖片檔案已損毀。

當啟用 detectCorrupted 選項且圖片已損毀時，會顯示此錯誤訊息。

此訊息沒有參數。

`detectCorrupted`

類型： boolean 預設值： false

如果此選項為 true，則會驗證圖片內容，以確保圖片未損毀。此驗證是使用 PHP 的 imagecreatefromstring 函式完成，這需要啟用 PHP GD 擴充功能。

`groups`

類型： array | string 預設值： null

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

`maxHeight`

類型： integer

如果設定，圖片檔案的高度必須小於或等於此值 (像素)。

`maxHeightMessage`

類型： string 預設值： 圖片高度過高 ({{ height }}px)。允許的最大高度為 {{ max_height }}px。

如果圖片高度超過 maxHeight 時，會顯示此錯誤訊息。

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

參數	描述
`{{ height }}`	目前的 (無效) 高度
`{{ max_height }}`	允許的最大高度

`maxPixels`

類型： integer

如果設定，圖片檔案的像素數量必須小於或等於此值。

`maxPixelsMessage`

類型： string 預設值： 圖片像素過多 ({{ pixels }} 像素)。預期的最大像素數量為 {{ max_pixels }} 像素。

如果圖片的像素數量超過 maxPixels 時，會顯示此錯誤訊息。

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

參數	描述
`{{ height }}`	目前的圖片像素
`{{ max_pixels }}`	允許的最大像素數量
`{{ pixels }}`	目前的像素數量
`{{ width }}`	目前的圖片寬度

`maxRatio`

類型： float

如果設定，圖片檔案的長寬比 (width / height) 必須小於或等於此值。

注意

此選項不適用於 SVG 檔案。如果您將其與 SVG 檔案一起使用，您將會看到 sizeNotDetectedMessage 選項中定義的錯誤訊息。

`maxRatioMessage`

類型： string 預設值： 圖片比例過大 ({{ ratio }})。允許的最大比例為 {{ max_ratio }}

如果圖片的長寬比超過 maxRatio 時，會顯示此錯誤訊息。

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

參數	描述
`{{ max_ratio }}`	允許的最大比例
`{{ ratio }}`	目前的 (無效) 比例

`maxWidth`

類型： integer

如果設定，圖片檔案的寬度必須小於或等於此值 (像素)。

`maxWidthMessage`

類型： string 預設值： 圖片寬度過高 ({{ width }}px)。允許的最大寬度為 {{ max_width }}px。

如果圖片寬度超過 maxWidth 時，會顯示此錯誤訊息。

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

參數	描述
`{{ max_width }}`	允許的最大寬度
`{{ width }}`	目前的 (無效) 寬度

`mimeTypes`

類型： array 或 string 預設值： image/*

您可以在 IANA 網站上找到現有的圖片 MIME 類型列表。

`mimeTypesMessage`

類型： string 預設值： 此檔案不是有效的圖片。

如果 mimeTypes 選項的所有值都是 image/* 的子集，則錯誤訊息將會改為： 檔案的 MIME 類型無效 ({{ type }})。允許的 MIME 類型為 {{ types }}。

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

參數	描述
`{{ file }}`	絕對檔案路徑
`{{ name }}`	基本檔案名稱
`{{ type }}`	給定檔案的 MIME 類型
`{{ types }}`	允許的 MIME 類型列表

`minHeight`

類型： integer

如果設定，圖片檔案的高度必須大於或等於此值 (像素)。

`minHeightMessage`

類型： string 預設值： 圖片高度過低 ({{ height }}px)。預期的最小高度為 {{ min_height }}px。

如果圖片高度小於 minHeight 時，會顯示此錯誤訊息。

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

參數	描述
`{{ height }}`	目前的 (無效) 高度
`{{ min_height }}`	允許的最小高度

`minPixels`

類型： integer

如果設定，圖片檔案的像素數量必須大於或等於此值。

`minPixelsMessage`

類型： string 預設值： 圖片像素過少 ({{ pixels }} 像素)。預期的最小像素數量為 {{ min_pixels }} 像素。

如果圖片的像素數量小於 minPixels 時，會顯示此錯誤訊息。

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

參數	描述
`{{ height }}`	目前的圖片像素
`{{ min_pixels }}`	允許的最小像素數量
`{{ pixels }}`	目前的像素數量
`{{ width }}`	目前的圖片寬度

`minRatio`

類型： float

如果設定，圖片檔案的長寬比 (width / height) 必須大於或等於此值。

注意

此選項不適用於 SVG 檔案。如果您將其與 SVG 檔案一起使用，您將會看到 sizeNotDetectedMessage 選項中定義的錯誤訊息。

`minRatioMessage`

類型： string 預設值： 圖片比例過小 ({{ ratio }})。預期的最小比例為 {{ min_ratio }}

如果圖片的長寬比小於 minRatio 時，會顯示此錯誤訊息。

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

參數	描述
`{{ min_ratio }}`	允許的最小比例
`{{ ratio }}`	目前的 (無效) 比例

`minWidth`

類型： integer

如果設定，圖片檔案的寬度必須大於或等於此值 (像素)。

`minWidthMessage`

類型： string 預設值： 圖片寬度過低 ({{ width }}px)。預期的最小寬度為 {{ min_width }}px。

如果圖片寬度小於 minWidth 時，會顯示此錯誤訊息。

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

參數	描述
`{{ min_width }}`	允許的最小寬度
`{{ width }}`	目前的 (無效) 寬度

`sizeNotDetectedMessage`

類型： string 預設值： 無法偵測到圖片尺寸。

如果系統無法判斷圖片的尺寸，將會顯示此錯誤訊息。這只會在至少設定一個尺寸約束條件選項時發生。

此訊息沒有參數。

注意

不支援偵測 SVG 圖片的尺寸。如果您使用以下任何選項，將會顯示此錯誤訊息： allowLandscape、 allowPortrait、 allowSquare、 maxRatio 和 minRatio。

這份作品，包括程式碼範例，皆以 Creative Commons BY-SA 3.0 授權條款授權。

版本