核心驗證器（Core Validators）

核心驗證器（Core Validators）

Yii 提供一系列常用的核心驗證器，主要存在于?yii\validators?命名空間之下。為了避免使用冗長的類名，你可以直接用昵稱來指定相應(yīng)的核心驗證器。比如你可以用?required?昵稱代指 yii\validators\RequiredValidator 類：

public function rules()
{
    return [
        [['email', 'password'], 'required'],
    ];
}

yii\validators\Validator::builtInValidators 屬性聲明了所有被支持的驗證器昵稱。

下面，我們將詳細(xì)介紹每一款驗證器的主要用法和屬性。

yii\validators\BooleanValidator

[
    // 檢查 "selected" 是否為 0 或 1，無視數(shù)據(jù)類型
    ['selected', 'boolean'],

    // 檢查 "deleted" 是否為布爾類型，即 true 或 false
    ['deleted', 'boolean', 'trueValue' => true, 'falseValue' => false, 'strict' => true],
]

該驗證器檢查輸入值是否為一個布爾值。

• trueValue： 代表真的值。默認(rèn)為?'1'。
• falseValue：代表假的值。默認(rèn)為?'0'。
• strict：是否要求待測輸入必須嚴(yán)格匹配?trueValue?或?falseValue。默認(rèn)為?false。

注意：因為通過 HTML 表單傳遞的輸入數(shù)據(jù)都是字符串類型，所以一般情況下你都需要保持 yii\validators\BooleanValidator::strict 屬性為假。

yii\captcha\CaptchaValidator

[
    ['verificationCode', 'captcha'],
]

該驗證器通常配合 yii\captcha\CaptchaAction 以及 yii\captcha\Captcha 使用，以確保某一輸入與 yii\captcha\Captcha 小部件所顯示的驗證代碼（verification code）相同。

• caseSensitive：對驗證代碼的比對是否要求大小寫敏感。默認(rèn)為 false。
• captchaAction：指向用于渲染 CAPTCHA 圖片的 yii\captcha\CaptchaAction 的?路由。默認(rèn)為?'site/captcha'。

• skipOnEmpty：當(dāng)輸入為空時，是否跳過驗證。默認(rèn)為 false，也就是輸入值為必需項。

  yii\validators\CompareValidator

[
    // 檢查 "password" 特性的值是否與 "password_repeat" 的值相同
    ['password', 'compare'],

    // 檢查年齡是否大于等于 30
    ['age', 'compare', 'compareValue' => 30, 'operator' => '>='],
]

該驗證器比較兩個特定輸入值之間的關(guān)系是否與?operator?屬性所指定的相同。

• compareAttribute：用于與原特性相比較的特性名稱。當(dāng)該驗證器被用于驗證某目標(biāo)特性時，該屬性會默認(rèn)為目標(biāo)屬性加后綴_repeat。舉例來說，若目標(biāo)特性為?password，則該屬性默認(rèn)為?password_repeat。
• compareValue：用于與輸入值相比較的常量值。當(dāng)該屬性與?compareAttribute?屬性同時被指定時，該屬性優(yōu)先被使用。
• operator：比較操作符。默認(rèn)為?==，意味著檢查輸入值是否與?compareAttribute?或?compareValue?的值相等。該屬性支持如下操作符：
  • ==：檢查兩值是否相等。比對為非嚴(yán)格模式。
  • ===：檢查兩值是否全等。比對為嚴(yán)格模式。
  • !=：檢查兩值是否不等。比對為非嚴(yán)格模式。
  • !==：檢查兩值是否不全等。比對為嚴(yán)格模式。
  • >：檢查待測目標(biāo)值是否大于給定被測值。
  • >=：檢查待測目標(biāo)值是否大于等于給定被測值。
  • <：檢查待測目標(biāo)值是否小于給定被測值。
  • <=：檢查待測目標(biāo)值是否小于等于給定被測值。

yii\validators\DateValidator

[
    [['from', 'to'], 'date'],
]

該驗證器檢查輸入值是否為適當(dāng)格式的 date，time，或者 datetime。另外，它還可以幫你把輸入值轉(zhuǎn)換為一個 UNIX 時間戳并保存到 yii\validators\DateValidator::timestampAttribute 屬性所指定的特性里。

• format：待測的 日期/時間 格式。請參考?date_create_from_format() 相關(guān)的 PHP 手冊了解設(shè)定格式字符串的更多細(xì)節(jié)。默認(rèn)值為'Y-m-d'。
• timestampAttribute：用于保存用輸入時間/日期轉(zhuǎn)換出來的 UNIX 時間戳的特性。

yii\validators\DefaultValueValidator

[
    // 若 "age" 為空，則將其設(shè)為 null
    ['age', 'default', 'value' => null],

    // 若 "country" 為空，則將其設(shè)為 "USA"
    ['country', 'default', 'value' => 'USA'],

    // 若 "from" 和 "to" 為空，則分別給他們分配自今天起，3 天后和 6 天后的日期。
    [['from', 'to'], 'default', 'value' => function ($model, $attribute) {
        return date('Y-m-d', strtotime($attribute === 'to' ? '+3 days' ：'+6 days'));
    }],
]

該驗證器并不進行數(shù)據(jù)驗證。而是，給為空的待測特性分配默認(rèn)值。

• value：默認(rèn)值，或一個返回默認(rèn)值的 PHP Callable 對象（即回調(diào)函數(shù)）。它們會分配給檢測為空的待測特性。PHP 回調(diào)方法的樣式如下：

function foo($model, $attribute) {
    // ... 計算 $value ...
    return $value;
}

補充：如何判斷待測值是否為空，被寫在另外一個話題的處理空輸入章節(jié)。

yii\validators\NumberValidator

[
    // 檢查 "salary" 是否為浮點數(shù)
    ['salary', 'double'],
]

該驗證器檢查輸入值是否為雙精度浮點數(shù)。他等效于?number?驗證器。

• max：上限值（含界點）。若不設(shè)置，則驗證器不檢查上限。

• min：下限值（含界點）。若不設(shè)置，則驗證器不檢查下限。

  yii\validators\EmailValidator

[
    // 檢查 "email" 是否為有效的郵箱地址
    ['email', 'email'],
]

該驗證器檢查輸入值是否為有效的郵箱地址。

• allowName：檢查是否允許帶名稱的電子郵件地址 (e.g.?張三 <John.san@example.com>)。 默認(rèn)為 false。
• checkDNS：檢查郵箱域名是否存在，且有沒有對應(yīng)的 A 或 MX 記錄。不過要知道，有的時候該項檢查可能會因為臨時性 DNS 故障而失敗，哪怕它其實是有效的。默認(rèn)為 false。
• enableIDN：驗證過程是否應(yīng)該考慮 IDN（internationalized domain names，國際化域名，也稱多語種域名，比如中文域名）。默認(rèn)為 false。要注意但是為使用 IDN 驗證功能，請先確保安裝并開啟?intl?PHP 擴展，不然會導(dǎo)致拋出異常。

yii\validators\ExistValidator

[
    // a1 需要在 "a1" 特性所代表的字段內(nèi)存在
    ['a1', 'exist'],

    // a1 必需存在，但檢驗的是 a1 的值在字段 a2 中的存在性
    ['a1', 'exist', 'targetAttribute' => 'a2'],

    // a1 和 a2 的值都需要存在，且它們都能收到錯誤提示
    [['a1', 'a2'], 'exist', 'targetAttribute' => ['a1', 'a2']],

    // a1 和 a2 的值都需要存在，只有 a1 能接收到錯誤信息
    ['a1', 'exist', 'targetAttribute' => ['a1', 'a2']],

    // 通過同時在 a2 和 a3 字段中檢查 a2 和 a1 的值來確定 a1 的存在性
    ['a1', 'exist', 'targetAttribute' => ['a2', 'a1' => 'a3']],

    // a1 必需存在，若 a1 為數(shù)組，則其每個子元素都必須存在。
    ['a1', 'exist', 'allowArray' => true],
]

該驗證器檢查輸入值是否在某表字段中存在。它只對活動記錄類型的模型類特性起作用，能支持對一個或多過字段的驗證。

• targetClass：用于查找輸入值的目標(biāo)?AR?類。若不設(shè)置，則會使用正在進行驗證的當(dāng)前模型類。
• targetAttribute：用于檢查輸入值存在性的?targetClass?的模型特性。
  • 若不設(shè)置，它會直接使用待測特性名（整個參數(shù)數(shù)組的首元素）。
  • 除了指定為字符串以外，你也可以用數(shù)組的形式，同時指定多個用于驗證的表字段，數(shù)組的鍵和值都是代表字段的特性名，值表示?targetClass?的待測數(shù)據(jù)源字段，而鍵表示當(dāng)前模型的待測特性名。
  • 若鍵和值相同，你可以只指定值。（如:['a2']?就代表?['a2'=>'a2']）
• filter：用于檢查輸入值存在性必然會進行數(shù)據(jù)庫查詢，而該屬性為用于進一步篩選該查詢的過濾條件。可以為代表額外查詢條件的字符串或數(shù)組（關(guān)于查詢條件的格式，請參考 yii\db\Query::where()）；或者樣式為?function ($query)?的匿名函數(shù)，$query參數(shù)為你希望在該函數(shù)內(nèi)進行修改的 yii\db\Query 對象。
• allowArray：是否允許輸入值為數(shù)組。默認(rèn)為 false。若該屬性為 true 且輸入值為數(shù)組，則數(shù)組的每個元素都必須在目標(biāo)字段中存在。值得注意的是，若用吧?targetAttribute?設(shè)為多元素數(shù)組來驗證被測值在多字段中的存在性時，該屬性不能設(shè)置為 true。

譯注：exist?和?unique?驗證器的機理和參數(shù)都相似，有點像一體兩面的陰和陽。

• 他們的區(qū)別是 exist 要求?targetAttribute?鍵所代表的的屬性在其值所代表字段中找得到；而 unique 正相反，要求鍵所代表的的屬性不能在其值所代表字段中被找到。
• 從另一個角度來理解：他們都會在驗證的過程中執(zhí)行數(shù)據(jù)庫查詢，查詢的條件即為where $v=$k (假設(shè)?targetAttribute?的其中一對鍵值對為?$k => $v)。unique 要求查詢的結(jié)果數(shù)?$count==0，而 exist 則要求查詢的結(jié)果數(shù)?$count>0
• 最后別忘了，unique 驗證器不存在?allowArray?屬性哦。

yii\validators\FileValidator

[
    // 檢查 "primaryImage" 是否為 PNG, JPG 或 GIF 格式的上傳圖片。
    // 文件大小必須小于  1MB
    ['primaryImage', 'file', 'extensions' => ['png', 'jpg', 'gif'], 'maxSize' => 1024*1024*1024],
]

該驗證器檢查輸入值是否為一個有效的上傳文件。

• extensions：可接受上傳的文件擴展名列表。它可以是數(shù)組，也可以是用空格或逗號分隔各個擴展名的字符串 (e.g. "gif, jpg")。 擴展名大小寫不敏感。默認(rèn)為 null，意味著所有擴展名都被接受。
• mimeTypes：可接受上傳的 MIME 類型列表。它可以是數(shù)組，也可以是用空格或逗號分隔各個 MIME 的字符串 (e.g. "image/jpeg, image/png")。 Mime 類型名是大小寫不敏感的。默認(rèn)為 null，意味著所有 MIME 類型都被接受。
• minSize：上傳文件所需最少多少 Byte 的大小。默認(rèn)為 null，代表沒有下限。
• maxSize：上傳文件所需最多多少 Byte 的大小。默認(rèn)為 null，代表沒有上限。
• maxFiles：給定特性最多能承載多少個文件。默認(rèn)為 1，代表只允許單文件上傳。若值大于一，那么輸入值必須為包含最多maxFiles?個上傳文件元素的數(shù)組。
• checkExtensionByMimeType：是否通過文件的 MIME 類型來判斷其文件擴展。若由 MIME 判定的文件擴展與給定文件的擴展不一樣，則文件會被認(rèn)為無效。默認(rèn)為 true，代表執(zhí)行上述檢測。

FileValidator?通常與 yii\web\UploadedFile 共同使用。請參考?文件上傳章節(jié)來了解有關(guān)文件上傳與上傳文件的檢驗的全部內(nèi)容。

yii\validators\FilterValidator

[
    // trim 掉 "username" 和 "email" 輸入
    [['username', 'email'], 'filter', 'filter' => 'trim', 'skipOnArray' => true],

    // 標(biāo)準(zhǔn)化 "phone" 輸入
    ['phone', 'filter', 'filter' => function ($value) {
        // 在此處標(biāo)準(zhǔn)化輸入的電話號碼
        return $value;
    }],
]

該驗證器并不進行數(shù)據(jù)驗證。而是，給輸入值應(yīng)用一個濾鏡，并在檢驗過程之后把它賦值回特性變量。

• filter：用于定義濾鏡的 PHP 回調(diào)函數(shù)?？梢詾槿趾瘮?shù)名，匿名函數(shù)，或其他。該函數(shù)的樣式必須是?function ($value) { return $newValue; }。該屬性不能省略，必須設(shè)置。
• skipOnArray：是否在輸入值為數(shù)組時跳過濾鏡。默認(rèn)為 false。請注意如果濾鏡不能處理數(shù)組輸入，你就應(yīng)該把該屬性設(shè)為 true。否則可能會導(dǎo)致 PHP Error 的發(fā)生。

技巧：如果你只是想要用 trim 處理下輸入值，你可以直接用?trim?驗證器的。

yii\validators\ImageValidator

[
    // 檢查 "primaryImage" 是否為適當(dāng)尺寸的有效圖片
    ['primaryImage', 'image', 'extensions' => 'png, jpg',
        'minWidth' => 100, 'maxWidth' => 1000,
        'minHeight' => 100, 'maxHeight' => 1000,
    ],
]

該驗證器檢查輸入值是否為代表有效的圖片文件。它繼承自?file?驗證器，并因此繼承有其全部屬性。除此之外，它還支持以下為圖片檢驗而設(shè)的額外屬性：

• minWidth：圖片的最小寬度。默認(rèn)為 null，代表無下限。
• maxWidth：圖片的最大寬度。默認(rèn)為 null，代表無上限。
• minHeight：圖片的最小高度。 默認(rèn)為 null，代表無下限。

• maxHeight：圖片的最大高度。默認(rèn)為 null，代表無上限。

  yii\validators\RangeValidator

[
    // 檢查 "level" 是否為 1、2 或 3 中的一個
    ['level', 'in', 'range' => [1, 2, 3]],
]

該驗證器檢查輸入值是否存在于給定列表的范圍之中。

• range：用于檢查輸入值的給定值列表。
• strict：輸入值與給定值直接的比較是否為嚴(yán)格模式（也就是類型與值都要相同，即全等）。默認(rèn)為 false。
• not：是否對驗證的結(jié)果取反。默認(rèn)為 false。當(dāng)該屬性被設(shè)置為 true，驗證器檢查輸入值是否不在給定列表內(nèi)。

• allowArray：是否接受輸入值為數(shù)組。當(dāng)該值為 true 且輸入值為數(shù)組時，數(shù)組內(nèi)的每一個元素都必須在給定列表內(nèi)存在，否則返回驗證失敗。

  yii\validators\NumberValidator

[
    // 檢查 "age" 是否為整數(shù)
    ['age', 'integer'],
]

該驗證器檢查輸入值是否為整形。

• max：上限值（含界點）。若不設(shè)置，則驗證器不檢查上限。

• min：下限值（含界點）。若不設(shè)置，則驗證器不檢查下限。

  yii\validators\RegularExpressionValidator

[
    // 檢查 "username" 是否由字母開頭，且只包含單詞字符
    ['username', 'match', 'pattern' => '/^[a-z]\w*$/i']
]

該驗證器檢查輸入值是否匹配指定正則表達式。

• pattern：用于檢測輸入值的正則表達式。該屬性是必須的，若不設(shè)置則會拋出異常。

• not：是否對驗證的結(jié)果取反。默認(rèn)為 false，代表輸入值匹配正則表達式時驗證成功。如果設(shè)為 true，則輸入值不匹配正則時返回匹配成功。

  yii\validators\NumberValidator

[
    // 檢查 "salary" 是否為數(shù)字
    ['salary', 'number'],
]

該驗證器檢查輸入值是否為數(shù)字。他等效于?double?驗證器。

• max：上限值（含界點）。若不設(shè)置，則驗證器不檢查上限。

• min：下限值（含界點）。若不設(shè)置，則驗證器不檢查下限。

  yii\validators\RequiredValidator

[
    // 檢查 "username" 與 "password" 是否為空
    [['username', 'password'], 'required'],
]

該驗證器檢查輸入值是否為空，還是已經(jīng)提供了。

• requiredValue：所期望的輸入值。若沒設(shè)置，意味著輸入不能為空。
• strict：檢查輸入值時是否檢查類型。默認(rèn)為 false。當(dāng)沒有設(shè)置?requiredValue?屬性時，若該屬性為 true，驗證器會檢查輸入值是否嚴(yán)格為 null；若該屬性設(shè)為 false，該驗證器會用一個更加寬松的規(guī)則檢驗輸入值是否為空。

當(dāng)設(shè)置了?requiredValue?屬性時，若該屬性為 true，輸入值與?requiredValue?的比對會同時檢查數(shù)據(jù)類型。

補充：如何判斷待測值是否為空，被寫在另外一個話題的處理空輸入章節(jié)。

yii\validators\SafeValidator

[
    // 標(biāo)記 "description" 為安全特性
    ['description', 'safe'],
]

該驗證器并不進行數(shù)據(jù)驗證。而是把一個特性標(biāo)記為安全特性。

yii\validators\StringValidator

[
    // 檢查 "username" 是否為長度 4 到 24 之間的字符串
    ['username', 'string', 'length' => [4, 24]],
]

該驗證器檢查輸入值是否為特定長度的字符串。并檢查特性的值是否為某個特定長度。

• length：指定待測輸入字符串的長度限制。該屬性可以被指定為以下格式之一：
  • 證書：the exact length that the string should be of;
  • 單元素數(shù)組：代表輸入字符串的最小長度 (e.g.?[8])。這會重寫?min?屬性。
  • 包含兩個元素的數(shù)組：代表輸入字符串的最小和最大長度(e.g.?[8, 128])。 這會同時重寫?min?和?max?屬性。
• min：輸入字符串的最小長度。若不設(shè)置，則代表不設(shè)下限。
• max：輸入字符串的最大長度。若不設(shè)置，則代表不設(shè)上限。

• encoding：待測字符串的編碼方式。若不設(shè)置，則使用應(yīng)用自身的 yii\base\Application::charset 屬性值，該值默認(rèn)為?UTF-8。

  yii\validators\FilterValidator

[
    // trim 掉 "username" 和 "email" 兩側(cè)的多余空格
    [['username', 'email'], 'trim'],
]

該驗證器并不進行數(shù)據(jù)驗證。而是，trim 掉輸入值兩側(cè)的多余空格。注意若該輸入值為數(shù)組，那它會忽略掉該驗證器。

yii\validators\UniqueValidator

[
    // a1 需要在 "a1" 特性所代表的字段內(nèi)唯一
    ['a1', 'unique'],

    // a1 需要唯一，但檢驗的是 a1 的值在字段 a2 中的唯一性
    ['a1', 'unique', 'targetAttribute' => 'a2'],

    // a1 和 a2 的組合需要唯一，且它們都能收到錯誤提示
    [['a1', 'a2'], 'unique', 'targetAttribute' => ['a1', 'a2']],

    // a1 和 a2 的組合需要唯一，只有 a1 能接收錯誤提示
    ['a1', 'unique', 'targetAttribute' => ['a1', 'a2']],

    // 通過同時在 a2 和 a3 字段中檢查 a2 和 a3 的值來確定 a1 的唯一性
    ['a1', 'unique', 'targetAttribute' => ['a2', 'a1' => 'a3']],
]

該驗證器檢查輸入值是否在某表字段中唯一。它只對活動記錄類型的模型類特性起作用，能支持對一個或多過字段的驗證。

• targetClass：用于查找輸入值的目標(biāo)?AR?類。若不設(shè)置，則會使用正在進行驗證的當(dāng)前模型類。
• targetAttribute：用于檢查輸入值唯一性的?targetClass?的模型特性。
  • 若不設(shè)置，它會直接使用待測特性名（整個參數(shù)數(shù)組的首元素）。
  • 除了指定為字符串以外，你也可以用數(shù)組的形式，同時指定多個用于驗證的表字段，數(shù)組的鍵和值都是代表字段的特性名，值表示?targetClass?的待測數(shù)據(jù)源字段，而鍵表示當(dāng)前模型的待測特性名。
  • 若鍵和值相同，你可以只指定值。（如:['a2']?就代表?['a2'=>'a2']）
• filter：用于檢查輸入值唯一性必然會進行數(shù)據(jù)庫查詢，而該屬性為用于進一步篩選該查詢的過濾條件?？梢詾榇眍~外查詢條件的字符串或數(shù)組（關(guān)于查詢條件的格式，請參考 yii\db\Query::where()）；或者樣式為?function ($query)?的匿名函數(shù)，$query參數(shù)為你希望在該函數(shù)內(nèi)進行修改的 yii\db\Query 對象。

譯注：exist?和?unique?驗證器的機理和參數(shù)都相似，有點像一體兩面的陰和陽。

• 他們的區(qū)別是 exist 要求?targetAttribute?鍵所代表的的屬性在其值所代表字段中找得到；而 unique 正相反，要求鍵所代表的的屬性不能在其值所代表字段中被找到。
• 從另一個角度來理解：他們都會在驗證的過程中執(zhí)行數(shù)據(jù)庫查詢，查詢的條件即為where $v=$k (假設(shè)?targetAttribute?的其中一對鍵值對為?$k => $v)。unique 要求查詢的結(jié)果數(shù)?$count==0，而 exist 則要求查詢的結(jié)果數(shù)?$count>0
• 最后別忘了，unique 驗證器不存在?allowArray?屬性哦。

yii\validators\UrlValidator

[
    // 檢查 "website" 是否為有效的 URL。若沒有 URI 方案，則給 "website" 特性加 "http://" 前綴
    ['website', 'url', 'defaultScheme' => 'http'],
]

該驗證器檢查輸入值是否為有效 URL。

• validSchemes：用于指定那些 URI 方案會被視為有效的數(shù)組。默認(rèn)為?['http', 'https']，代表?http?和?https?URLs 會被認(rèn)為有效。
• defaultScheme：若輸入值沒有對應(yīng)的方案前綴，會使用的默認(rèn) URI 方案前綴。默認(rèn)為 null，代表不修改輸入值本身。
• enableIDN：驗證過程是否應(yīng)該考慮 IDN（internationalized domain names，國際化域名，也稱多語種域名，比如中文域名）。默認(rèn)為 false。要注意但是為使用 IDN 驗證功能，請先確保安裝并開啟?intl?PHP 擴展，不然會導(dǎo)致拋出異常。