CFileValidator
| Пакет | system.validators |
|---|---|
| Наследование | класс CFileValidator » CValidator » CComponent |
| С момента | 1.0 |
| Исходный код | framework/validators/CFileValidator.php |
Он использует модель класса и имя атрибута для получения информации о загруженном файле. Затем он проверяет, был ли файл успешно загружен, соответствует ли размер файла лимиту и разрешён ли тип файла.
Этот валидатор попытается извлечь загруженные данные, если атрибут не был предварительно задан. Обратите внимание, что это невозможно, если входной параметр является табличным:
foreach($models as $i=>$model)
$model->attribute = CUploadedFile::getInstance($model, "[$i]attribute");
Пожалуйста, обратите внимание, что для множественного загрузки файлов необходимо использовать CUploadedFile::getInstances. При использовании CFileValidator с активной записью часто используется следующий код:
$model->attribute = CUploadedFile::getInstance($model, "attribute");
if($model->save())
{
// single upload
$model->attribute->saveAs($path);
// multiple upload
foreach($model->attribute as $file)
$file->saveAs($path);
}
Вы можете использовать CFileValidator для проверки атрибута файла.
В дополнение к свойству message для задания пользовательского сообщения об ошибке, CFileValidator имеет несколько пользовательских сообщений об ошибках, которые можно задать для разных сценариев проверки. Если файл слишком большой, вы можете использовать свойство tooLarge для определения пользовательского сообщения об ошибке. Аналогично для tooSmall, wrongType и tooMany. Сообщения могут содержать дополнительные плейсхолдеры, которые будут заменены фактическим содержимым. В дополнение к плейсхолдеру "{attribute}", распознаваемому всеми валидаторами (см. CValidator), CFileValidator допускает указание следующих плейсхолдеров:
Общедоступные свойства
| Свойство | Тип | Описание | Определено |
|---|---|---|---|
| allowEmpty | boolean | требуется ли атрибут для загрузки файла или нет. | CFileValidator |
| attributes | array | список атрибутов, которые необходимо проверить. | CValidator |
| builtInValidators | array | список встроенных валидаторов (имя=>класс) | CValidator |
| enableClientValidation | boolean | выполнять ли проверку на стороне клиента. | CValidator |
| except | array | список сценариев, к которым валидатор не должен применяться. | CValidator |
| maxFiles | integer | максимальное количество файлов, которое может содержать данный атрибут. | CFileValidator |
| maxSize | integer | максимальное количество байтов, требуемое для загруженного файла. | CFileValidator |
| message | string | определённое пользователем сообщение об ошибке. | CValidator |
| mimeTypes | mixed | список MIME-типов файла, которые разрешены для загрузки. | CFileValidator |
| minSize | integer | минимальное количество байтов, требуемое для загруженного файла. | CFileValidator |
| on | array | список сценариев, к которым должен применяться валидатор. | CValidator |
| safe | boolean | являются ли атрибуты, указанные с этим валидатором, безопасными для массового назначения. | CValidator |
| skipOnError | boolean | пропустить ли эту проверку, если для текущего атрибута уже есть ошибка проверки. | CValidator |
| tooLarge | string | сообщение об ошибке, используемое, когда загруженный файл слишком большой. | CFileValidator |
| tooMany | string | сообщение об ошибке, используемое, если количество нескольких загрузок превышает лимит. | CFileValidator |
| tooSmall | string | сообщение об ошибке, используемое, когда загруженный файл слишком маленький. | CFileValidator |
| types | mixed | список расширений имён файлов, которые разрешены для загрузки. | CFileValidator |
| wrongMimeType | string | сообщение об ошибке, используемое, если MIME-тип загруженного файла не указан среди mimeTypes. | CFileValidator |
| wrongType | string | сообщение об ошибке, используемое, когда у загруженного файла есть имя расширения, которое не указано среди types. | CFileValidator |
Защищенные свойства
| Свойство | Тип | Описание | Определено |
|---|---|---|---|
| sizeLimit | integer | Возвращает максимальный разрешенный размер для загруженных файлов. | CFileValidator |
Публичные методы
| Метод | Описание | Определено в |
|---|---|---|
| __call() | Вызывает метод с указанным именем, который не является методом класса. | CComponent |
| __get() | Возвращает значение свойства, список обработчиков событий или поведение на основе его имени. | CComponent |
| __isset() | Проверяет, является ли значение свойства null. | CComponent |
| __set() | Устанавливает значение свойства компонента. | CComponent |
| __unset() | Устанавливает свойство компонента в null. | CComponent |
| applyTo() | Возвращает значение, указывающее, применим ли валидатор к указанному сценарию. | CValidator |
| asa() | Возвращает объект поведения с указанным именем. | CComponent |
| attachBehavior() | Присоединяет поведение к этому компоненту. | CComponent |
| attachBehaviors() | Присоединяет список поведений к компоненту. | CComponent |
| attachEventHandler() | Присоединяет обработчик событий к событию. | CComponent |
| canGetProperty() | Определяет, может ли свойство быть прочитано. | CComponent |
| canSetProperty() | Определяет, может ли свойство быть установлено. | CComponent |
| clientValidateAttribute() | Возвращает JavaScript, необходимый для выполнения проверки на стороне клиента. | CValidator |
| createValidator() | Создаёт объект валидатора. | CValidator |
| detachBehavior() | Отсоединяет поведение от компонента. | CComponent |
| detachBehaviors() | Отсоединяет все поведения от компонента. | CComponent |
| detachEventHandler() | Отсоединяет существующий обработчик событий. | CComponent |
| disableBehavior() | Отключает присоединённое поведение. | CComponent |
| disableBehaviors() | Отключает все поведения, присоединённые к этому компоненту. | CComponent |
| enableBehavior() | Включает присоединённое поведение. | CComponent |
| enableBehaviors() | Включает все присоединённые поведения к этому компоненту. | CComponent |
| evaluateExpression() | Вычисляет выражение PHP или обратный вызов в контексте этого компонента. | CComponent |
| getEventHandlers() | Возвращает список присоединённых обработчиков событий для события. | CComponent |
| hasEvent() | Определяет, определено ли событие. | CComponent |
| hasEventHandler() | Проверяет, есть ли для события присоединённые обработчики. | CComponent |
| hasProperty() | Определяет, определено ли свойство. | CComponent |
| raiseEvent() | Вызывает событие. | CComponent |
| sizeToBytes() | Преобразует размер в стиле php.ini в байты. | CFileValidator |
| validate() | Проверяет указанный объект. | CValidator |
Защищенные методы
| Метод | Описание | Определено в |
|---|---|---|
| addError() | Добавляет ошибку о заданном атрибуте в активную запись. | CValidator |
| emptyAttribute() | Вызывает ошибку, чтобы проинформировать пользователя об отсутствии атрибута. | CFileValidator |
| getSizeLimit() | Возвращает максимальный размер, разрешенный для загружаемых файлов. | CFileValidator |
| isEmpty() | Проверяет, пустое ли заданное значение. | CValidator |
| validateAttribute() | Устанавливает атрибут и затем проверяет его, используя validateFile. | CFileValidator |
| validateFile() | Внутренне проверяет объект файла. | CFileValidator |
Подробное описание свойств
allowEmpty свойство
public boolean $allowEmpty;
указывается ли, требуется ли атрибуту файл для загрузки. По умолчанию false, что означает, что файл должен быть загружен. Если файл не загружен, свойство owner устанавливается в null, чтобы предотвратить установку произвольных значений.
maxFiles свойство
public integer $maxFiles;
максимальное количество файлов, которое может содержать данный атрибут. По умолчанию 1, что означает одиночную загрузку файла. Определением большего числа становится возможной многократная загрузка.
maxSize свойство
public integer $maxSize;
максимальное число байтов, требуемое для загружаемого файла. По умолчанию null, что означает отсутствие ограничения. Обратите внимание, что ограничение размера также зависит от настройки 'upload_max_filesize' в php.ini и значения скрытого поля 'MAX_FILE_SIZE'.
См. также
mimeTypes свойство (доступно начиная с v1.1.11)
public mixed $mimeTypes;
список MIME-типов файлов, которые разрешены для загрузки. Это может быть массив или строка, содержащая MIME-типы, разделенные пробелами или запятыми (например, "image/gif, image/jpeg"). MIME-типы регистронезависимы. По умолчанию null, что означает, что разрешены все MIME-типы. Для использования этого свойства необходимо установить расширение PECL fileinfo.
minSize свойство
public integer $minSize;
минимальное количество байтов, требуемое для загружаемого файла. По умолчанию null, что означает отсутствие ограничения.
См. также
sizeLimit свойство только для чтения
protected integer getSizeLimit()
Возвращает максимальный размер, разрешенный для загружаемых файлов. Это определяется на основе трех факторов:
- 'upload_max_filesize' в php.ini
- 'MAX_FILE_SIZE' скрытое поле
- maxSize
tooLarge свойство
public string $tooLarge;
сообщение об ошибке, используемое, когда загружаемый файл слишком большой.
См. также
tooMany свойство
public string $tooMany;
сообщение об ошибке, используемое, если количество многократных загрузок превышает предел.
tooSmall свойство
public string $tooSmall;
сообщение об ошибке, используемое, когда загружаемый файл слишком мал.
См. также
types свойство
public mixed $types;
список расширений имён файлов, которые разрешены для загрузки. Это может быть массив или строка, содержащая имена расширений файлов, разделенных пробелами или запятыми (например, "gif, jpg"). Имена расширений регистронезависимы. По умолчанию null, что означает, что разрешены все расширения имён файлов.
wrongMimeType свойство (доступно начиная с v1.1.11)
public string $wrongMimeType;
сообщение об ошибке, используемое, когда загруженный файл имеет тип MIME, который не указан в списке mimeTypes. Для использования этого свойства необходимо установить расширение PECL fileinfo.
wrongType свойство
public string $wrongType;
сообщение об ошибке, используемое, когда у загруженного файла имя расширения не указано в списке types.
Подробное описание методов
emptyAttribute() метод
protected void emptyAttribute(CModel $object, string $attribute) | ||
| $object | CModel | валидируемый объект |
| $attribute | строка | валидируемое свойство |
protected function emptyAttribute($object, $attribute)
{
if($this->safe)
$object->$attribute=null;
if(!$this->allowEmpty)
{
$message=$this->message!==null?$this->message : Yii::t('yii','{attribute} cannot be blank.');
$this->addError($object,$attribute,$message);
}
}
Вызывает ошибку, чтобы проинформировать конечного пользователя об пустом свойстве. Устанавливает свойство owner в null, чтобы предотвратить установку произвольных значений.
getSizeLimit() метод
protected integer getSizeLimit() | ||
| {return} | целое число | лимит размера загружаемых файлов. |
protected function getSizeLimit()
{
$limit=ini_get('upload_max_filesize');
$limit=$this->sizeToBytes($limit);
if($this->maxSize!==null && $limit>0 && $this->maxSize<$limit)
$limit=$this->maxSize;
if(isset($_POST['MAX_FILE_SIZE']) && $_POST['MAX_FILE_SIZE']>0 && $_POST['MAX_FILE_SIZE']<$limit)
$limit=$_POST['MAX_FILE_SIZE'];
return $limit;
}
Возвращает максимальный разрешенный размер загружаемых файлов. Он определяется на основе трех факторов:
- 'upload_max_filesize' в php.ini
- 'MAX_FILE_SIZE' скрытое поле
- maxSize
sizeToBytes() метод (доступен начиная с v1.1.11)
public integer sizeToBytes(string $sizeStr) | ||
| $sizeStr | строка | строка размера, подлежащая преобразованию. |
| {return} | целое число | количество байтов в данной строке размера. |
public function sizeToBytes($sizeStr)
{
// get the latest character
switch (strtolower(substr($sizeStr, -1)))
{
case 'm': return (int)$sizeStr * 1048576; // 1024 * 1024
case 'k': return (int)$sizeStr * 1024; // 1024
case 'g': return (int)$sizeStr * 1073741824; // 1024 * 1024 * 1024
default: return (int)$sizeStr; // do nothing
}
}
Преобразует размер в стиле php.ini в байты.
Примеры строк размера: 150, 1g, 500k, 5M (суффикс размера нечувствителен к регистру). Если вы передаете сюда число с дробной частью, то все после десятичной точки будет проигнорировано (общее поведение значений php.ini). Например, значение 1.5G будет обрабатываться как 1G, а в результате будет возвращено число 1073741824. Этот метод является публичным (раньше был приватным) с версии 1.1.11.
validateAttribute() метод
protected void validateAttribute(CModel $object, string $attribute) | ||
| $object | CModel | валидируемый объект |
| $attribute | строка | валидируемое свойство |
protected function validateAttribute($object, $attribute)
{
$files=$object->$attribute;
if($this->maxFiles > 1)
{
if(!is_array($files) || !isset($files[0]) || !$files[0] instanceof CUploadedFile)
$files = CUploadedFile::getInstances($object, $attribute);
if(array()===$files)
return $this->emptyAttribute($object, $attribute);
if(count($files) > $this->maxFiles)
{
$message=$this->tooMany!==null?$this->tooMany : Yii::t('yii', '{attribute} cannot accept more than {limit} files.');
$this->addError($object, $attribute, $message, array('{attribute}'=>$attribute, '{limit}'=>$this->maxFiles));
}
else
foreach($files as $file)
$this->validateFile($object, $attribute, $file);
}
else
{
if (is_array($files))
{
if (count($files) > 1)
{
$message=$this->tooMany!==null?$this->tooMany : Yii::t('yii', '{attribute} cannot accept more than {limit} files.');
$this->addError($object, $attribute, $message, array('{attribute}'=>$attribute, '{limit}'=>$this->maxFiles));
return;
}
else
$file = empty($files) ? null : reset($files);
}
else
$file = $files;
if(!$file instanceof CUploadedFile)
{
$file = CUploadedFile::getInstance($object, $attribute);
if(null===$file)
return $this->emptyAttribute($object, $attribute);
}
$this->validateFile($object, $attribute, $file);
}
}
Устанавливает свойство и затем валидирует с помощью validateFile. При возникновении ошибки сообщение об ошибке добавляется к объекту.
validateFile() метод
protected void validateFile(CModel $object, string $attribute, CUploadedFile $file) | ||
| $object | CModel | валидируемый объект |
| $attribute | строка | валидируемое свойство |
| $file | CUploadedFile | загруженный файл, проверяемый по набору правил |
protected function validateFile($object, $attribute, $file)
{
$error=(null===$file ? null : $file->getError());
if($error==UPLOAD_ERR_INI_SIZE || $error==UPLOAD_ERR_FORM_SIZE || $this->maxSize!==null && $file->getSize()>$this->maxSize)
{
$message=$this->tooLarge!==null?$this->tooLarge : Yii::t('yii','The file "{file}" is too large. Its size cannot exceed {limit} bytes.');
$this->addError($object,$attribute,$message,array('{file}'=>$file->getName(), '{limit}'=>$this->getSizeLimit()));
if($error!==UPLOAD_ERR_OK)
return;
}
elseif($error!==UPLOAD_ERR_OK)
{
if($error==UPLOAD_ERR_NO_FILE)
return $this->emptyAttribute($object, $attribute);
elseif($error==UPLOAD_ERR_PARTIAL)
throw new CException(Yii::t('yii','The file "{file}" was only partially uploaded.',array('{file}'=>$file->getName())));
elseif($error==UPLOAD_ERR_NO_TMP_DIR)
throw new CException(Yii::t('yii','Missing the temporary folder to store the uploaded file "{file}".',array('{file}'=>$file->getName())));
elseif($error==UPLOAD_ERR_CANT_WRITE)
throw new CException(Yii::t('yii','Failed to write the uploaded file "{file}" to disk.',array('{file}'=>$file->getName())));
elseif(defined('UPLOAD_ERR_EXTENSION') && $error==UPLOAD_ERR_EXTENSION) // available for PHP 5.2.0 or above
throw new CException(Yii::t('yii','A PHP extension stopped the file upload.'));
else
throw new CException(Yii::t('yii','Unable to upload the file "{file}" because of an unrecognized error.',array('{file}'=>$file->getName())));
}
if($this->minSize!==null && $file->getSize()<$this->minSize)
{
$message=$this->tooSmall!==null?$this->tooSmall : Yii::t('yii','The file "{file}" is too small. Its size cannot be smaller than {limit} bytes.');
$this->addError($object,$attribute,$message,array('{file}'=>$file->getName(), '{limit}'=>$this->minSize));
}
if($this->types!==null)
{
if(is_string($this->types))
$types=preg_split('/[\s,]+/',strtolower($this->types),-1,PREG_SPLIT_NO_EMPTY);
else
$types=$this->types;
if(!in_array(strtolower($file->getExtensionName()),$types))
{
$message=$this->wrongType!==null?$this->wrongType : Yii::t('yii','The file "{file}" cannot be uploaded. Only files with these extensions are allowed: {extensions}.');
$this->addError($object,$attribute,$message,array('{file}'=>$file->getName(), '{extensions}'=>implode(', ',$types)));
}
}
if($this->mimeTypes!==null && !empty($file->tempName))
{
if(function_exists('finfo_open'))
{
$mimeType=false;
if($info=finfo_open(defined('FILEINFO_MIME_TYPE') ? FILEINFO_MIME_TYPE : FILEINFO_MIME))
$mimeType=finfo_file($info,$file->getTempName());
}
elseif(function_exists('mime_content_type'))
$mimeType=mime_content_type($file->getTempName());
else
throw new CException(Yii::t('yii','In order to use MIME-type validation provided by CFileValidator fileinfo PECL extension should be installed.'));
if(is_string($this->mimeTypes))
$mimeTypes=preg_split('/[\s,]+/',strtolower($this->mimeTypes),-1,PREG_SPLIT_NO_EMPTY);
else
$mimeTypes=$this->mimeTypes;
if($mimeType===false || !in_array(strtolower($mimeType),$mimeTypes))
{
$message=$this->wrongMimeType!==null?$this->wrongMimeType : Yii::t('yii','The file "{file}" cannot be uploaded. Only files of these MIME-types are allowed: {mimeTypes}.');
$this->addError($object,$attribute,$message,array('{file}'=>$file->getName(), '{mimeTypes}'=>implode(', ',$mimeTypes)));
}
}
}
Внутренняя валидация объекта файла.
© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CFileValidator