ActiveRecord File Attachment Extension for Yii2

This extension provides support for ActiveRecord file attachment.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through composer.

Either run

or add

to the require section of your composer.json.

If you wish to use [[yii2tech\ar\file\ImageFileBehavior]], you will also need to install yiisoft/yii2-imagine, which is not required by default. In order to do so either run

or add

to the require section of your composer.json.

Usage

This extension provides support for ActiveRecord file attachment. Attached files are stored inside separated file storage, which does not connected with ActiveRecord database.

This extension based on yii2tech/file-storage, and uses it as a file saving layer. Thus attached files can be stored at any file storage such as local file system, Amazon S3 and so on.

First of all, you need to configure file storage, which will be used for attached files:

You should use [[\yii2tech\ar\file\FileBehavior]] behavior in order to allow your ActiveRecord file saving. This can be done in following way:

Usage of this behavior requires extra columns being present at the owner entity (database table):

• [[\yii2tech\ar\file\FileBehavior::fileExtensionAttribute]] - used to store file extension, allowing to determine file type
• [[\yii2tech\ar\file\FileBehavior::fileVersionAttribute]] - used to track file version, allowing browser cache busting

For example, DDL for the 'item' table may look like following:

Once behavior is attached to may use saveFile() method on your ActiveRecord instance:

This method will save source file inside file storage bucket, which has been specified inside behavior configuration, and update file extension and version attributes.

You may delete existing file using deleteFile() method:

Note: attached file will be automatically removed on owner deletion (delete() method invocation).

You may check existence of the file, get its content or URL:

Tip: you may setup [[\yii2tech\ar\file\FileBehavior::defaultFileUrl]] in order to make getFileUrl() returning some default image URL in case actual attached file is missing.

Working with web forms

Usually files for ActiveRecord are setup via web interface using file upload mechanism. [[\yii2tech\ar\file\FileBehavior]] provides a special virtual property for the owner, which name is determined by [[\yii2tech\ar\file\FileBehavior::fileAttribute]]. This property can be used to pass [[\yii\web\UploadedFile]] instance or local file name, which should be attached to the ActiveRecord. This property is processed on owner saving, and if set will trigger file saving. For example:

Attention: do NOT declare [[\yii2tech\ar\file\FileBehavior::fileAttribute]] attribute in the owner ActiveRecord class. Make sure it does not conflict with any existing owner field or virtual property.

If [[\yii2tech\ar\file\FileBehavior::autoFetchUploadedFile]] is enabled, behavior will attempt to fetch uploaded file automatically before owner saving.

You may setup a validation rules for the file virtual attribute inside your model, specifying restrictions for the attached file type, extension and so on:

Inside view file you can use file virtual property for the form file input as it belongs to the owner model itself:

Inside the controller you don't need any special code:

File transformation

Saving file "as it is" is not always enough for ActiveRecord attachment. Often files require some processing, like image resizing, for example.

[[\yii2tech\ar\file\TransformFileBehavior]] is an enhanced version of the [[FileBehavior]] developed for the managing files, which require some processing (transformations). You should setup [[\yii2tech\ar\file\TransformFileBehavior::transformCallback]] to specify actual file processing algorithm, and [[\yii2tech\ar\file\TransformFileBehavior::fileTransformations]] providing the list of named processing and their specific settings. For example:

In case of usage [[\yii2tech\ar\file\TransformFileBehavior]] methods fileExists(), getFileContent() and getFileUrl() accepts first parameter as a transformation name, for which result should be returned:

Some file transformations may require changing the file extension. For example: you may want to create a preview for the .psd file in .jpg format. You may specify file extension per each transformation using [[\yii2tech\ar\file\TransformFileBehavior::transformationFileExtensions]]. For example:

You may face the issue, when settings for some file transformations change or new transformation added, as your project evolves, making existing saved files outdated. In this case you can use [[\yii2tech\ar\file\TransformFileBehavior::regenerateFileTransformations()]] method to regenerate transformation files with new settings using some existing transformation as source. For example:

Image file transformation

The most common file transformation use case is an image resizing. Thus a special behavior [[\yii2tech\ar\file\ImageFileBehavior]] is provided. This behavior provides image resize transformation via yiisoft/yii2-imagine extension. Configuration example:

Note: this package does not include "yiisoft/yii2-imagine", you should install it yourself.