In Yii, we need to follow three key steps: first, use the UploadedFile class in the model to set properties and define verification rules; second, configure the enctype of the form in the view to multipart/form-data to support file input; finally, obtain the uploaded file instance in the controller and save it safely after verification. In addition, you should also pay attention to common problems such as PHP file size limitation, upload directory permissions, front-end and back-end verification combinations, to ensure that the upload process is safe and reliable.

Handling file uploads in Yii forms isn't too bad once you get the basics down. The main points are: set up your model to handle files, make sure the form is configured correctly for file input, and process the upload safely on the backend.

Let's go through a few key steps and things to watch out for.

1. Set Up Your Model to Accept File Uploads

In Yii, you usually work with UploadedFile to handle file inputs. So first, you need a property in your model to store the uploaded file instance.

For example, if you're uploading an avatar image:

 class UserForm extends Model
{
    public $avatar;

    public function rules()
    {
        Return [
            ['avatar', 'file', 'extensions' => 'png, jpg, jpeg'],
        ];
    }
}

This sets up a rule that only allows .png , .jpg , or .jpeg files. You can also specify things like max size, mime types, etc., depending on your needs.

One thing to note: this $avatar property doesn't map directly to a database field — it's just a temporary holder for the uploaded file during form submission.

2. Use ActiveForm with enctype="multipart/form-data"

When building your form, you must include the correct encoding type so that files can be uploaded.

In your view:

 use yii\widgets\ActiveForm;
use yii\helpers\Html;

$form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]);
echo $form->field($model, 'avatar')->fileInput();
echo Html::submitButton('Upload', ['class' => 'btn btn-primary']);
ActiveForm::end();

Without setting enctype="multipart/form-data" on the form tag, the file won't be sent at all.

Also, if you're using AJAX to submit the form, make sure your JS code handles file data properly (eg, using FormData ), otherwise the upload will fail silently.

3. Process the Upload in Your Controller

Once the form is submitted, you'll want to validate and move the file somewhere safe.

Here's how that usually looks in a controller action:

 public function actionUpload()
{
    $model = new UserForm();

    if (Yii::$app->request->isPost) {
        $model->avatar = UploadedFile::getInstance($model, 'avatar');

        if ($model->validate()) {
            $uploadPath = Yii::getAlias('@webroot/uploads/avatars');
            $fileName = 'user_' . time() . '.' . $model->avatar->extension;
            $model->avatar->saveAs($uploadPath . '/' . $fileName);

            // Optionally save filename to DB or do more processing
            Yii::$app->session->setFlash('success', 'File uploaded successfully.');
        } else {
            Yii::$app->session->setFlash('error', 'Invalid file or upload failed.');
        }
    }

    return $this->render('upload', ['model' => $model]);
}

A couple of important things here:

• Always use UploadedFile::getInstance() to get the uploaded file.
• Save to a secure path — make sure the target directory exists and has proper permissions.
• Consider renaming the file to avoid overwrites and potential security issues (like user-supplied filenames).

If you're handling multiple files, you can use UploadedFile::getInstances() instead.

4. Common Issues and Gotchas

• Max file size restrictions
  PHP limits file uploads by default. If users can't upload large files, check your php.ini settings:

  • upload_max_filesize
  • post_max_size You might need to increase these values ??and restart your server.

• Incorrect file permissions
  Make sure the upload directory is writable by the web server user. Otherwise, saveAs() will fail without obvious errors.

• Validation not running
  If validation doesn't trigger, double-check whether you're actually calling validate() and that the file input name matches the model attribute.

• Frontend-only validation isn't enough
  Even if you use JavaScript to restrict file types before upload, always validate again on the backend — it's easy for someone to bypass frontend checks.

That should cover most cases when dealing with file uploads in Yii forms. It's straightforward once everything is wired up right, but there are a few places where things can quietly break if you miss a step.

Basically that's it.

The above is the detailed content of How do I handle file uploads in Yii forms?. For more information, please follow other related articles on the PHP Chinese website!