Uploading Files ¶

Uploading files in Yii is usually done with the help of yii\web\UploadedFile which encapsulates each uploaded file as an UploadedFile object. Combined with yii\widgets\ActiveForm and models, you can easily implement a secure file uploading mechanism.

Creating Models ¶

Like working with plain text inputs, to upload a single file you would create a model class and use an attribute of the model to keep the uploaded file instance. You should also declare a validation rule to validate the file upload. For example,

namespace app\models;

use yii\base\Model;
use yii\web\UploadedFile;

class UploadForm extends Model
{
    /**
     * @var UploadedFile
     */
    public $imageFile;

    public function rules()
    {
        return [
            [['imageFile'], 'file', 'skipOnEmpty' => false, 'extensions' => 'png, jpg'],
        ];
    }
    
    public function upload()
    {
        if ($this->validate()) {
            $this->imageFile->saveAs('uploads/' . $this->imageFile->baseName . '.' . $this->imageFile->extension);
            return true;
        } else {
            return false;
        }
    }
}

In the code above, the imageFile attribute is used to keep the uploaded file instance. It is associated with a file validation rule which uses yii\validators\FileValidator to ensure a file with extension name png or jpg is uploaded. The upload() method will perform the validation and save the uploaded file on the server.

The file validator allows you to check file extensions, size, MIME type, etc. Please refer to the Core Validators section for more details.

Tip: If you are uploading an image, you may consider using the image validator instead. The image validator is implemented via yii\validators\ImageValidator which verifies if an attribute has received a valid image that can be then either saved or processed using the Imagine Extension.

Rendering File Input ¶

Next, create a file input in a view:

<?php
use yii\widgets\ActiveForm;
?>

<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]) ?>

    <?= $form->field($model, 'imageFile')->fileInput() ?>

    <button>Submit</button>

<?php ActiveForm::end() ?>

It is important to remember that you add the enctype option to the form so that the file can be properly uploaded. The fileInput() call will render a <input type="file"> tag which will allow users to select a file to upload.

Tip: since version 2.0.8, fileInput adds enctype option to the form automatically when file input field is used.

Wiring Up ¶

Now in a controller action, write the code to wire up the model and the view to implement file uploading:

namespace app\controllers;

use Yii;
use yii\web\Controller;
use app\models\UploadForm;
use yii\web\UploadedFile;

class SiteController extends Controller
{
    public function actionUpload()
    {
        $model = new UploadForm();

        if (Yii::$app->request->isPost) {
            $model->imageFile = UploadedFile::getInstance($model, 'imageFile');
            if ($model->upload()) {
                // file is uploaded successfully
                return;
            }
        }

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

In the above code, when the form is submitted, the yii\web\UploadedFile::getInstance() method is called to represent the uploaded file as an UploadedFile instance. We then rely on the model validation to make sure the uploaded file is valid and save the file on the server.

Uploading Multiple Files ¶

You can also upload multiple files at once, with some adjustments to the code listed in the previous subsections.

First you should adjust the model class by adding the maxFiles option in the file validation rule to limit the maximum number of files allowed to upload. Setting maxFiles to 0 means there is no limit on the number of files that can be uploaded simultaneously. The maximum number of files allowed to be uploaded simultaneously is also limited with PHP directive max_file_uploads, which defaults to 20. The upload() method should also be updated to save the uploaded files one by one.

namespace app\models;

use yii\base\Model;
use yii\web\UploadedFile;

class UploadForm extends Model
{
    /**
     * @var UploadedFile[]
     */
    public $imageFiles;

    public function rules()
    {
        return [
            [['imageFiles'], 'file', 'skipOnEmpty' => false, 'extensions' => 'png, jpg', 'maxFiles' => 4],
        ];
    }
    
    public function upload()
    {
        if ($this->validate()) { 
            foreach ($this->imageFiles as $file) {
                $file->saveAs('uploads/' . $file->baseName . '.' . $file->extension);
            }
            return true;
        } else {
            return false;
        }
    }
}

In the view file, you should add the multiple option to the fileInput() call so that the file upload field can receive multiple files. You also need to change imageFiles to imageFiles[] so that the attribute values are submitted as an array:

<?php
use yii\widgets\ActiveForm;
?>

<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]) ?>

    <?= $form->field($model, 'imageFiles[]')->fileInput(['multiple' => true, 'accept' => 'image/*']) ?>

    <button>Submit</button>

<?php ActiveForm::end() ?>

And finally in the controller action, you should call UploadedFile::getInstances() instead of UploadedFile::getInstance() to assign an array of UploadedFile instances to UploadForm::imageFiles.

namespace app\controllers;

use Yii;
use yii\web\Controller;
use app\models\UploadForm;
use yii\web\UploadedFile;

class SiteController extends Controller
{
    public function actionUpload()
    {
        $model = new UploadForm();

        if (Yii::$app->request->isPost) {
            $model->imageFiles = UploadedFile::getInstances($model, 'imageFiles');
            if ($model->upload()) {
                // file is uploaded successfully
                return;
            }
        }

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