trntv/yii2-file-kit

Yii2 file upload and storage kit

Friday, May 18, 2018
by trntv
Repository
20 Watchers
118 Stars
82,942 Installations

PHP
21 Dependents
1 Suggesters
83 Forks
28 Open issues
23 Versions
9 % Grown

The README.md

GitHub Workflow Status Packagist Version (custom server) , _(*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 yii2-starter-kit/yii2-file-kit

or add, _(*7)

"yii2-starter-kit/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' => 'trntv\filekit\Storage',
    'useDirindex' => true,
    'baseUrl' => '@web/uploads'
    'filesystem'=> ...
        // OR
    'filesystemComponent' => ...
],

There are several ways to configure trntv\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 trntv\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'=>'trntv\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'=>'trntv\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'=>'trntv\filekit\actions\ViewAction',
       ]
    ];
}

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

Standalone usage, _(*17)

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

Standalone usage - without model, _(*18)

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

With ActiveForm, _(*19)

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

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' => 'trntv\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' => 'trntv\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'=>'trntv\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());
               }
               ...
           ]
       ];
}

The Versions

18/05 2018

dev-master

9999999-dev

Yii2 file upload and storage kit

yii2-extension yii2-file-kit

Yii2 file upload and storage kit

trntv/yii2-file-kit

The README.md

Demo

Installation

File Storage

Using Closure

Using filesystem builder

Using third-party extensions

Actions

Upload Action

Delete Action

View (Download) Action

Upload Widget

Upload Widget events

UploadBehavior

Validation

Tips

Adding watermark

The Versions

dev-master

The Requires

The Development Requires

by Eugene Terentev

1.3.1

The Requires

The Development Requires

by Eugene Terentev

1.3.0

The Requires

The Development Requires

by Eugene Terentev

1.2.1

The Requires

The Development Requires

by Eugene Terentev

1.2.0

The Requires

The Development Requires

by Eugene Terentev

1.1.8

The Requires

The Development Requires

by Eugene Terentev

1.1.7

The Requires

The Development Requires

by Eugene Terentev

dev-25-reset-upload

The Requires

The Development Requires

by Eugene Terentev

1.1.6

The Requires

The Development Requires

by Eugene Terentev

1.1.5

The Requires

The Development Requires

by Eugene Terentev

1.1.4

The Requires

The Development Requires

by Eugene Terentev

1.1.3

The Requires

The Development Requires

by Eugene Terentev

1.1.2

The Requires

The Development Requires

by Eugene Terentev

1.1.1

The Requires

The Development Requires

by Eugene Terentev

1.1.0

The Requires

The Development Requires