Правило safe в Yii2 и массовое присваивание атрибутов
В Yii2 правило safe разрешает загрузить атрибут из массива через load() или setAttributes(). Разберём, когда оно нужно, почему load() может вернуть true при пропущенном поле и как ограничить набор полей, доступных для изменения.
Что делает правило safe в Yii2
Правило safe разрешает массовое присваивание атрибута в текущем сценарии модели. Его проверка проходит без оценки значения. Если поле доступно для записи, модель может принять строку, число или массив. Ограничения на тип, длину и формат задаются отдельными валидаторами.
В стандартной реализации yii\base\Model список доступных полей строится на основе rules() и текущего сценария. Обычные валидаторы вроде required, string и email тоже делают свои атрибуты доступными для массового присваивания, если их правила действуют в этом сценарии. Поэтому рядом с правилом string отдельное правило safe обычно лишнее.
public function rules(): array
{
return [
// Разрешаем загрузить имя и проверяем его длину.
['displayName', 'string', 'max' => 80],
// Разрешаем загрузить значение без проверки его содержимого.
['uiHint', 'safe'],
];
}Этот фрагмент предполагает, что модель объявляет оба атрибута. Для необязательного текстового поля обычно подходит string с нужным ограничением длины. Правило safe пригодится, если проверка содержимого делегирована другому слою и этот слой получает значение до его использования.
Что происходит при вызове load()
Массовое присваивание переносит несколько значений из массива за один вызов. По умолчанию load($data) ищет вложенный массив под ключом, который возвращает formName(). Например, модель ProfileForm обычно ожидает данные под ключом ProfileForm. Вызов load($data, '') читает поля из массива верхнего уровня. При прямом вызове setAttributes($values) передаётся сам массив полей.
Затем Yii присваивает значения только атрибутам из safeAttributes(). Прочие ключи по умолчанию пропускаются, а уже установленные значения этих атрибутов сохраняются. Если разрешённого поля нет в запросе, его значение также остаётся прежним. При обновлении записи это различие важно, когда отсутствие поля и явно переданное пустое значение имеют разный смысл.
load() выполняет загрузку без запуска валидаторов. Результат true показывает, что Yii нашёл ожидаемую область данных или получил непустой плоский массив. При этом все переданные ключи могут быть пропущены. Для проверки значений вызовите validate(), а ошибки читайте через getErrors(). Если вы работаете напрямую с Active Record, метод save() по умолчанию сам запускает валидацию.
Как сценарий ограничивает список полей
Сценарий задаёт контекст операции. Например, настройки профиля могут принимать отображаемое имя и описание, а смена пароля требует своего набора полей. Для правил можно указать on и except, чтобы включать или исключать отдельные сценарии. Правило без этих параметров действует во всех сценариях, где соответствующий атрибут активен.
Если модель переопределяет scenarios(), список атрибутов в текущем сценарии определяет, какие поля доступны для массового присваивания. Запись !accountId оставляет accountId активным для валидации, но исключает его из массового присваивания. Это удобно, когда идентификатор устанавливает приложение и его всё равно нужно проверять. Для проверки потребуется действующее правило в rules().
public function scenarios(): array
{
$scenarios = parent::scenarios();
// Идентификатор устанавливает приложение перед валидацией.
$scenarios['editProfile'] = ['displayName', 'bio', '!accountId'];
return $scenarios;
}Установите сценарий до загрузки данных, например $model->scenario = 'editProfile'. Имя сценария выбирает сервер по выполняемой операции. Если сценарий выбирается из запроса, клиент может получить доступ к набору полей, предназначенному для другой операции. Проверку прав на изменение конкретной записи выполняйте отдельно.
Рабочий пример модели формы на PHP 8.3–8.5
Модель формы позволяет описать входные поля отдельно от атрибутов записи. В примере свойства имеют тип mixed, потому что Yii записывает в них значения запроса до валидации. Если объявить public string $bio, массив в этом поле может вызвать TypeError уже при загрузке. С mixed валидатор вернёт обычную ошибку поля. После успешной проверки можно передать значения в код со строгими типами.
<?php
declare(strict_types=1);
namespace app\models;
use yii\base\Model;
final class ProfileForm extends Model
{
public mixed $displayName = '';
public mixed $bio = '';
public function rules(): array
{
return [
['displayName', 'required'],
['displayName', 'string', 'max' => 80],
// Пустая строка очищает описание. Массив и null вызовут ошибку.
['bio', 'string', 'max' => 1000, 'skipOnEmpty' => false],
];
}
}Во фрагменте контроллера ниже $profile — уже загруженная запись профиля, право на изменение которой проверено. Обработчик редактирования подставляет текущие значения перед загрузкой. Поэтому отсутствующее поле сохраняет старое значение, а пустая строка в bio очищает описание. Пример рассчитан на Yii2, установленный с зависимостями, совместимыми с выбранной версией PHP.
$form = new \app\models\ProfileForm();
$form->displayName = $profile->display_name;
$form->bio = $profile->bio ?? '';
$data = \Yii::$app->request->post($form->formName());
if (!is_array($data)) {
throw new \yii\web\BadRequestHttpException('Ожидаются данные формы профиля.');
}
$form->load($data, '');
if (!$form->validate()) {
return $this->render('edit', ['model' => $form]);
}
// Переносим только проверенные поля этой операции.
$profile->display_name = $form->displayName;
$profile->bio = $form->bio;
if (!$profile->save()) {
$form->addError('displayName', 'Не удалось сохранить профиль.');
return $this->render('edit', ['model' => $form]);
}
return $this->redirect(['edit']);Здесь валидация формы проверяет входные значения, а save() сохраняет проверки, заданные в модели записи. Служебные поля вроде role и owner_id отсутствуют в форме и в коде переноса. Даже если их ключи появятся в запросе, этот обработчик их не присвоит.
Границы защиты и отличия от Yii 1.1
Ограничение применяется на этапе массового присваивания с включённой проверкой списка разрешённых полей. Прямое присваивание $model->role = $value и вызов setAttributes($data, false) обходят ограничение safeAttributes(). Для второго варианта Yii использует список attributes(), поэтому в Active Record могут оказаться доступны служебные столбцы. Передавайте в такие операции только значения, отобранные приложением.
Правило safe также оставляет значение без преобразования. Текст при выводе в HTML экранируйте через Html::encode(). Если редактор допускает форматированный HTML, обрабатывайте его по правилам проекта перед выводом. Валидация значения, разрешение на изменение поля и подготовка текста к выводу выполняют разные задачи.
В Yii 1.1 часто использовали $model->attributes = $data, а отдельное правило unsafe исключало атрибут из массового присваивания. В Yii2 обычно загружают данные через load() или setAttributes(). При переносе старой модели проверьте список атрибутов в каждом сценарии. Если поле должно проверяться, но заполняется только приложением, используйте префикс ! в scenarios().
Чек-лист, если поле теряется или принимается лишнее
- Сверьте структуру запроса с
formName(). Для плоских данных передайте вload()пустое имя формы. - Посмотрите
safeAttributes()у модели перед загрузкой. Если поля нет в списке, проверьте текущий сценарий,rules(), параметрыonиexceptи переопределениеscenarios(). - Сравните значение поля сразу после
load()и послеvalidate(). Так можно увидеть, было ли поле пропущено при загрузке или его значение изменило правило вродеfilterилиdefault. При ошибке посмотритеgetErrors(). - Для каждого разрешённого поля определите допустимые тип, длину и пустое значение. Проверьте, как обработчик различает отсутствие ключа, пустую строку и
null. - Проверьте форму с лишним служебным ключом и с массивом вместо строки. Служебное поле должно сохранить прежнее значение, а неверный тип должен обрабатываться как ошибка формы.
Частые вопросы
Нужно ли добавлять safe к полю с правилом string?
Обычно достаточно правила string. В стандартной модели Yii2 оно разрешает массовое присваивание, если действует в текущем сценарии. Если переопределён метод scenarios(), дополнительно проверьте список атрибутов этого сценария.
Почему load() вернул true, а значение поля не изменилось?
Yii мог найти ожидаемую область данных и пропустить ключ при присваивании. Проверьте точное имя ключа и наличие атрибута в safeAttributes() текущего сценария.
Как валидировать поле, которое клиенту нельзя менять?
Укажите атрибут с префиксом ! в списке текущего сценария и оставьте для него действующее правило в rules(). Присвойте значение из доверенного источника на сервере до вызова validate().