README

Behavior for ActiveRecord models for easy file uploading. Following formats of uploads are supported:

POST method upload (http://php.net/manual/en/features.file-upload.post-method.php)
Remote file url
Base64
Server path

Package includes 3 classes:

FileUploadBehavior - main behavior to handle files
ImageUploadBehavior - extended class to handle image files, includes functional to fix image orientation for jpeg images, parameter originalFolder to store files in original size folder (for ImageAction)
ImageAction - makes different sizes for images, that stores resized files to folder near original folder, named "{width}x{height}.

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist platx/yii2-upload "*"

or add

"platx/yii2-upload": "*"

to the require section of your composer.json file.

Configuring

Attach the behavior in your ActiveRecord model:

public function behaviors()
{
    return [
        'upload' => [
            'class' => 'platx\upload\FileUploadBehavior',
            // or 'class' => 'platx\upload\ImageUploadBehavior',
            'attributes' => ['image'], // Model attributes to handle
            'scenarios' => ['default'], // Scenarios to handle
            'basePath' => '@app/web/uploads', // Base path on server to store files
            'baseUrl' => '/uploads', // Base url to make url
            // Additional configuration
        ]
    ];
}

Configuration options for platx\upload\FileUploadBehavior:

attributes - Model attribute names that should be handled. Type: array. Required parameter.
scenarios - Scenarios to handle (by default scenarios from owner model taken). Type: array.
prefix - Prefix for file attribute, which will be posted. Type: string. Default value: file_.
basePath - Server path to store files (with alias or absolute server path). Type: string. Default value: @app/web/uploads.
baseUrl - Base url to build url link to file. Type: string. Default value: /uploads.
handleNotUploadedFiles - Whether handle not POST method uploads (base64, remote url, server path). Type: boolean. Default value: false.
nameTemplate - File name template or generating new name. Default value: {id}_{name}.{ext} . Can be:
- true - Generate new file name
- false - Keep original file name
- string - Template to generate new file name, can be with variables:
  - {id} - Record id (if is composite key, will be imploded)
  - {attribute} - Model attribute name
  - {name} - File name
  - {ext} - File extension
- \Closure - the callback function to be executed. The anonymous function should have the following signature:
```
function ($model, $attribute, $file)
```
  where: - $model - Owner model instance - $attribute - Current attribute name for file upload - $file - Current UploadedFile instance to save For example:
```
function ($model, $attribute, $file) {
    return 'file_' . $model->id . '.' .$file->extension;
}
```
modelFolder - Whether add model name folder. Default value: true. Can be:
- true - Include model folder
- false - Do not include model folder
- string - Static string to be included
- \Closure - The callback function to be executed. The anonymous function should have the following signature:
```
function ($model, $attribute, $file)
```
  where: - $model: Owner model instance - $attribute: Current attribute name for file upload - $file: Current UploadedFile instance to upload For example:
```
function ($model, $attribute, $file) {
    return 'my_' . $model::getTableSchema()->fullName;
}
```
dynamicFolder - Whether generate dynamic folder. Default value: true. Can be:
- true - Generate dynamic folder (3 nesting levels), using model primary key
- false - Do not include dynamic folder
- string - Static string
- \Closure - The callback function to be executed. The anonymous function should have the following signature:
```
function ($model, $attribute, $file)
```
  where: - $model: Owner model instance - $attribute: Current attribute name for file upload - $file: Current UploadedFile instance to upload For example:
```
function ($model, $attribute, $file) {
    return $model::getTableSchema()->fullName . '_' .uniqid();
}
```
attributeFolder - Whether add attribute folder. Default value: true. Can be:
- true - Add folder with attribute name
- false - Do not include attribute folder
- string - Static string
- \Closure - The callback function to be executed. The anonymous function should have the following signature:
```
function ($model, $attribute, $file)
```
  where: - $model: Owner model instance - $attribute: Current attribute name for file upload - $file: Current UploadedFile instance to upload For example:
```
function ($model, $attribute, $file) {
    return $model::getTableSchema()->fullName . '_' .uniqid();
}
```
instanceByName - Whether get file instance by attribute name. Type: boolean. Default value: false.
deleteWithOwner - Whether delete file with model record deleting. Type: boolean. Default value: true.
deleteTempFile - Whether delete temporary file after saving. Type: boolean. Default value: true.
messageUploadNotSupported - Error message if upload type is not supported. Type: string. Default value: From message source.
messageUnableSaveFile - Error message if unable to save file to destination folder. Type: string. Default value: From message source.
messageUnableHandleFile - Error message if unable to handle upload and make UploadedFile instance. Type: string. Default value: From message source.
messageUnableCreateDirectory - Error message if unable to create destination folder for file. Type: string. Default value: From message source.
originalFolder(ImageUploadBehavior) - Folder name to store original image files (can be changed in ImageUploadBehavior). Type: string. Default value: original.

Then to enable file validation you should add it to rules array of your model, like this:

public function rules()
{
    return [
        ['file_image', 'file'],
        // or
        ['file_image', 'image'],
    ];
}

Attach the image action in your controller class:

public function actions()
{
    return [
        'upload' => [
            'image' => [
                'class' => \platx\upload\ImageAction::className(),
                'basePath' => '@app/web/uploads',
                'originalFolder' => 'original',
                'sizeList' => ['500x500','200x0','0x300']
            ],
        ]
    ];
}

where:

sizeList - Allowed size list of generated images, if is empty, any size is allowed to resize. If you will put 0 to width or height, it will be dynamic to save image ratio.
basePath - Base server path to image uploads
originalFolder - Folder name with original image files

Add following to your UrlManager component rules:

    '/uploads/<width:[\d]+>x<height:[\d]+>/<link:[\w\d\/-_\.]+>' => '/your_controller/image'

Usage

To upload file, use attribute name {prefix}_{attribute}. To get file url, use function getFileUrl($attribute, $isAbsolute) for FileUploadBehavior and getFileUrl($attribute, $isAbsolute, $size) for ImageUploadBehavior with ImageAction configured, where:

$attribute - your attribute name
$isAbsolute - whether to make your file url absolute or not (with http/https and your site domain)
$size - Size to needed size of image in {width}x{height} format

For example, you have attribute named image and behavior property prefix equals file_. To upload file, you should use attribute file_image. To get file url, you should use function of your model $model->getFileUrl('image').

Example form file:

<?php $form = \yii\bootstrap\ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]); ?>
    <?= $form->field($model, 'file_image')->fileInput() ?>
    <div class="form-group">
        <?= \yii\helpers\Html::submitButton('Upload', ['class' => 'btn btn-primary']) ?>
    </div>
<?php $form->end(); ?>

Example view file:

<?= \yii\helpers\Html::img($model->getFileUrl('image')); ?>

or using with ImageAction configured:

<?= \yii\helpers\Html::img($model->getFileUrl('image', false, '100x100')); ?>

platx / yii2-upload

Maintainers

Details

README

Installation

Configuring

Usage