ptheofan / yii2-file-upload-behavior
A highly customisable system to make file-uploads management as trivial as it should be.
Installs: 49
Dependents: 0
Suggesters: 3
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Type:yii2-extension
Requires
- php: >=7.4.0
- ext-fileinfo: *
- ptheofan/yii2-file-helper: ^1.0
- ptheofan/yii2-image-helper: ^1.0
- yiisoft/yii2: ^2.0
Suggests
- creocoder/yii2-flysystem: Required if you use the build-in FlySystem storage manager fascade
- yiisoft/yii2-imagine: Required for the built-in image uploads versioning
README
Documentation is incomplete and will add more info and examples as time allows. Feel free to open an issue if there's something you want to ask or add to the documentation. Currently it comes with a facade for the FlySystem only. In due time I will add also a facade for basic local filesystem
The entire system is designed to be very customisable and extensible. There are a couple of points that can be (and will be) improved to make it as extensible and customisable as possible whilst keeping it sane.
This is an example of how to configure the behavior and use it to allow users to upload their avatar. In this example we want to achieve the following
- access the property as
avatar
- see
modelVirtualAttribute
- see
- store the filename to the database in the column
avatar_hash
.- see
modelAttribute
- see
- Filename prefixed with row ID, filename the SHA1 of the file and suffix the version
- For this we set the
filenameGenerator
to use theCallbackFilenameGenerator
- Configure it to not include the extension (versions will take care of .ext in this case)
- For this we set the
- Keep the following versions
- Unresized upload in PNG format
PngBaseVersion
. Final name will look something like 512-deadbeef.png - sm (width = 64 pixels) with suffix
-sm
. Final name will look something like 512-deadbeef-sm.png - md (width = 256 pixels) with suffix
-md
. Final name will look something like 512-deadbeef-md.png - lg (width = 512 pixels) with suffix
-lg
. Final name will look something like 512-deadbeef-lg.png
- Unresized upload in PNG format
When the request arrives simply push the UploadedFile
instance to the avatar
model property, save the model and voila, image stored as per the provided configuration and all versions are generated.
$model->avatar = UploadedFile::getInstance($model, 'file'); $model->save();
When you want to retrieve a particular version of the uploaded file simply call
$url = $model->avatar->getVersion('sm')->getUrl();
You can also print the object to get detailed helpful information
echo $model->avatar;
In the following example we configure our model to use the database column avatar_hash
to store the file information in the database and set virtual attribute to avatar. This means
$model->avatar_hash
contains the value produced by the generator (you typically don't care to touch this column).$model->avatar
is your accessor to the image. Calling$model->avatar->getVersion('sm')->getUrl()
will return the complete URL to the small version of the file.- You can assign an uploaded file as simple as
$model->avatar = UploadedFile::getInstance($model, 'avatar')
- You can push a base64 encoded image as simply as
$model->avatar = $myBase64EncodedImage
- You can push a binary string simply by
$model->avatar = file_get_contents('my_file.png')
public function behaviors(): array { return [ 'avatar' => [ 'class' => FileAttribute::class, 'modelAttribute' => 'avatar_hash', 'modelVirtualAttribute' => 'avatar', 'generateAfterInsert' => true, 'filenameGenerator' => [ 'class' => CallbackFilenameGenerator::class, 'withExt' => false, 'callback' => static function(string $file, ActiveRecord $model, IFileAttribute $attr) { return sprintf('%s-%s', $model->id, sha1_file($file)); } ], 'versions' => [ [ // will produce 'class' => PngBaseVersion::class, 'name' => 'sm', 'basePath' => '/avatars', 'baseUrl' => 'https://cdn.example.com/avatars', 'width' => 64, 'suffix' => '-sm', ], [ 'class' => PngResizedVersion::class, 'name' => 'sm', 'basePath' => '/avatars', 'baseUrl' => 'https://cdn.example.com/avatars', 'width' => 64, 'suffix' => '-sm', ], [ 'class' => PngResizedVersion::class, 'name' => 'md', 'basePath' => '/avatars', 'baseUrl' => 'https://cdn.example.com/avatars', 'width' => 256, 'suffix' => '-md', ], [ 'class' => PngResizedVersion::class, 'name' => 'lg', 'basePath' => '/avatars', 'baseUrl' => 'https://cdn.example.com/avatars', 'width' => 512, 'suffix' => '-lg', ], ], ], ]; } ```