grandmasterx/filekit

Yii2 file upload and storage kit

, _(*1)

This kit is designed to automate routine processes of uploading files, their saving and storage. It includes: - File upload widget (based on Blueimp File Upload) - Component for storing files (built on top of flysystem) - Actions to download, delete, and view (download) files - Behavior for saving files in the model and delete files when you delete a model, _(*2)

Here you can see list of available filesystem adapters, _(*3)

Demo

Since file kit is a part of yii2-starter-kit it's demo can be found in starter kit demo here., _(*4)

Installation

The preferred way to install this extension is through composer., _(*5)

Either run, _(*6)

php composer.phar require grandmasterx/yii2-file-kit

or add, _(*7)

"grandmasterx/yii2-file-kit": "@stable"

to the require section of your composer.json file., _(*8)

File Storage

To work with the File Kit you need to configure FileStorage first. This component is a layer of abstraction over the filesystem - Its main task to take on the generation of a unique name for each file and trigger corresponding events., _(*9)

'fileStorage'=>[
    'class' => 'grandmasterx\filekit\Storage',
    'baseUrl' => '@web/uploads'
    'filesystem'=> ...
        // OR
    'filesystemComponent' => ...    
],

There are several ways to configure grandmasterx\filekit\Storage to work with flysystem., _(*10)

Using Closure

'fileStorage'=>[
    ...
    'filesystem'=> function() {
        $adapter = new \League\Flysystem\Adapter\Local('some/path/to/storage');
        return new League\Flysystem\Filesystem($adapter);
    }
]

Using filesystem builder

• Create a builder class that implements grandmasterx\filekit\filesystem\FilesystemBuilderInterface and implement method build which returns filesystem object. See examples/
• Add to your configuration:

'fileStorage'=>[
    ...
    'filesystem'=> [
        'class' => 'app\components\FilesystemBuilder',
        'path' => '@webroot/uploads'
        ...
    ]
]

Read more about flysystem at http://flysystem.thephpleague.com/, _(*11)

Using third-party extensions

• Create filesystem component (example uses creocoder/yii2-flysystem)

'components' => [
    ...
    'fs' => [
        'class' => 'creocoder\flysystem\LocalFilesystem',
        'path' => '@webroot/files'
    ],
    ...
]

• Set filesystem component name in storage configuration:

'components' => [
    ...
    'fileStorage'=>[
        'filesystemComponent'=> 'fs'
    ],
    ...
]

Actions

File Kit contains several Actions to work with uploads., _(*12)

Upload Action

Designed to save the file uploaded by the widget, _(*13)

public function actions(){
    return [
           'upload'=>[
               'class'=>'grandmasterx\filekit\actions\UploadAction',
               //'deleteRoute' => 'my-custom-delete', // my custom delete action for deleting just uploaded files(not yet saved)
               //'fileStorage' => 'myfileStorage', // my custom fileStorage from configuration
               'multiple' => true,
               'disableCsrf' => true,
               'responseFormat' => Response::FORMAT_JSON,
               'responsePathParam' => 'path',
               'responseBaseUrlParam' => 'base_url',
               'responseUrlParam' => 'url',
               'responseDeleteUrlParam' => 'delete_url',
               'responseMimeTypeParam' => 'type',
               'responseNameParam' => 'name',
               'responseSizeParam' => 'size',
               'deleteRoute' => 'delete',
               'fileStorage' => 'fileStorage', // Yii::$app->get('fileStorage')
               'fileStorageParam' => 'fileStorage', // ?fileStorage=someStorageComponent
               'sessionKey' => '_uploadedFiles',
               'allowChangeFilestorage' => false,
               'validationRules' => [
                    ...
               ],
               'on afterSave' => function($event) {
                    /* @var $file \League\Flysystem\File */
                    $file = $event->file
                    // do something (resize, add watermark etc)
               }
           ]
       ];
}

See additional settings in the corresponding class, _(*14)

Delete Action

public function actions(){
    return [
       'delete'=>[
           'class'=>'grandmasterx\filekit\actions\DeleteAction',
           //'fileStorage' => 'fileStorageMy', // my custom fileStorage from configuration(such as in the upload action)
       ]
    ];
}

See additional settings in the corresponding class, _(*15)

View (Download) Action

public function actions(){
    return [
       'view'=>[
           'class'=>'grandmasterx\filekit\actions\ViewAction',
       ]
    ];
}

See additional settings in the corresponding class, _(*16)

Upload Widget

Standalone usage, _(*17)

echo \grandmasterx\filekit\widget\Upload::widget([
    'model' => $model,
    'attribute' => 'files',
    'url' => ['upload'],
    'sortable' => true,
    'maxFileSize' => 10 * 1024 * 1024, // 10Mb
    'minFileSize' => 1 * 1024 * 1024, // 1Mb
    'maxNumberOfFiles' => 3 // default 1,
    'acceptFileTypes' => new JsExpression('/(\.|\/)(gif|jpe?g|png)$/i'),
    'showPreviewFilename' => false,
    'clientOptions' => [ ...other blueimp options... ]
]);

Standalone usage - without model, _(*18)

echo \grandmasterx\filekit\widget\Upload::widget([
    'name' => 'filename',
    'hiddenInputId' => 'filename', // must for not use model
    'url' => ['upload'],
    'sortable' => true,
    'maxFileSize' => 10 * 1024 * 1024, // 10Mb
    'minFileSize' => 1 * 1024 * 1024, // 1Mb
    'maxNumberOfFiles' => 3 // default 1,
    'acceptFileTypes' => new JsExpression('/(\.|\/)(gif|jpe?g|png)$/i'),
    'showPreviewFilename' => false,
    'clientOptions' => [ ...other blueimp options... ]
]);

With ActiveForm, _(*19)

echo $form->field($model, 'files')->widget(
    '\grandmasterx\filekit\widget\Upload',
    [
        'url' => ['upload'],
        'sortable' => true,
        'maxFileSize' => 10 * 1024 * 1024, // 10 MiB
        'maxNumberOfFiles' => 3,
        'clientOptions' => [ ...other blueimp options... ]
    ]
);

Upload Widget events

Upload widget trigger some of built-in blueimp events: - start - fail - done - always, _(*20)

You can use them directly or add your custom handlers in options:, _(*21)

'clientOptions' => [ 
    'start' => new JsExpression('function(e, data) { ... do something ... }'),
    'done' => new JsExpression('function(e, data) { ... do something ... }'),
    'fail' => new JsExpression('function(e, data) { ... do something ... }'),
    'always' => new JsExpression('function(e, data) { ... do something ... }'),
 ]

UploadBehavior

This behavior is designed to save uploaded files in the corresponding relation., _(*22)

Somewhere in model:, _(*23)

For multiple files, _(*24)

 public function behaviors()
 {
    return [
        'file' => [
            'class' => 'grandmasterx\filekit\behaviors\UploadBehavior',
            'filesStorage' => 'myfileStorage', // my custom fileStorage from configuration(for properly remove the file from disk)
            'multiple' => true,
            'attribute' => 'files',
            'uploadRelation' => 'uploadedFiles',
            'pathAttribute' => 'path',
            'baseUrlAttribute' => 'base_url',
            'typeAttribute' => 'type',
            'sizeAttribute' => 'size',
            'nameAttribute' => 'name',
            'orderAttribute' => 'order'
        ],
    ];
 }

For single file upload, _(*25)

 public function behaviors()
 {
     return [
          'file' => [
              'class' => 'grandmasterx\filekit\behaviors\UploadBehavior',
              'filesStorage' => 'fileStorageMy', // my custom fileStorage from configuration(for properly remove the file from disk)
              'attribute' => 'file',
              'pathAttribute' => 'path',
              'baseUrlAttribute' => 'base_url',
               ...
          ],
      ];
 }

See additional settings in the corresponding class., _(*26)

Validation

There are two ways you can perform validation over uploads. On the client side validation is performed by Blueimp File Upload. Here is documentation about available options., _(*27)

On the server side validation is performed by [[yii\web\UploadAction]], where you can configure validation rules for [[yii\base\DynamicModel]] that will be used in validation process, _(*28)

Tips

Adding watermark

Install intervention/image library, _(*29)

composer require intervention/image

Edit your upload actions as so, _(*30)

public function actions(){
    return [
           'upload'=>[
               'class'=>'grandmasterx\filekit\actions\UploadAction',
               ...
               'on afterSave' => function($event) {
                    /* @var $file \League\Flysystem\File */
                    $file = $event->file;

                    // create new Intervention Image
                    $img = Intervention\Image\ImageManager::make($file->read());

                    // insert watermark at bottom-right corner with 10px offset
                    $img->insert('public/watermark.png', 'bottom-right', 10, 10);

                    // save image
                    $file->put($img->encode());
               }
               ...
           ]
       ];
}