README

为Yii2的ActiveRecord文件附件扩展

本扩展提供了对ActiveRecord文件附件的支持。

有关许可证信息，请参阅LICENSE文件。

安装

安装此扩展的首选方式是通过composer。

运行

php composer.phar require --prefer-dist yii2tech/ar-file

或添加

"yii2tech/ar-file": "*"

到您的composer.json文件中的require部分。

如果您想使用[[yii2tech\ar\file\ImageFileBehavior]]，还需要安装yiisoft/yii2-imagine，这不是默认要求的。为此，可以运行

php composer.phar require --prefer-dist yiisoft/yii2-imagine

或添加

"yiisoft/yii2-imagine": "*"

到您的composer.json文件中的require部分。

使用

此扩展提供了对ActiveRecord文件附件的支持。附件文件存储在独立的文件存储中，与ActiveRecord数据库不连接。

本扩展基于yii2tech/file-storage，并使用它作为文件保存层。因此，附件文件可以存储在任何文件存储中，如本地文件系统、Amazon S3等。

首先，您需要配置用于附件文件的文件存储

return [
    'components' => [
        'fileStorage' => [
            'class' => 'yii2tech\filestorage\local\Storage',
            'basePath' => '@webroot/files',
            'baseUrl' => '@web/files',
            'filePermission' => 0777,
            'buckets' => [
                'item' => [
                    'baseSubPath' => 'item',
                ],
            ]
        ],
        // ...
    ],
    // ...
];

您应该使用[[\yii2tech\ar\file\FileBehavior]]行为来允许您的ActiveRecord文件保存。可以通过以下方式完成

use yii2tech\ar\file\FileBehavior;

class Item extends \yii\db\ActiveRecord
{
    public function behaviors()
    {
        return [
            'file' => [
                'class' => FileBehavior::className(),
                'fileStorageBucket' => 'item',
                'fileExtensionAttribute' => 'fileExtension',
                'fileVersionAttribute' => 'fileVersion',
            ],
        ];
    }
    // ...
}

使用此行为需要额外列存在于所有者实体（数据库表）中

• [[\yii2tech\ar\file\FileBehavior::fileExtensionAttribute]] - 用于存储文件扩展名，允许确定文件类型
• [[\yii2tech\ar\file\FileBehavior::fileVersionAttribute]] - 用于跟踪文件版本，允许浏览器缓存清除

例如，'item'表的DDL可能如下所示

CREATE TABLE `Item`
(
   `id` integer NOT NULL AUTO_INCREMENT,
   `name` varchar(64) NOT NULL,
   `description` text,
   `fileExtension` varchar(10),
   `fileVersion` integer,
    PRIMARY KEY (`id`)
) ENGINE InnoDB;

一旦行为附加到，就可以在ActiveRecord实例上使用saveFile()方法

$model = Item::findOne(1);
$model->saveFile('/path/to/source/file.dat');

此方法将在行为配置中指定的文件存储桶中保存源文件，并更新文件扩展名和版本属性。

您可以使用deleteFile()方法删除现有文件

$model = Item::findOne(1);
$model->deleteFile();

注意：在调用删除方法（delete()方法）时，将自动删除附件文件。

您可以通过检查文件是否存在、获取其内容或URL来操作文件

$model = Item::findOne(1);
if ($model->fileExists()) {
    echo $model->getFileUrl(); // outputs file URL
    echo $model->getFileContent(); // outputs file content
} else {
    echo 'No file attached';
}

提示：您可以通过设置[[\yii2tech\ar\file\FileBehavior::defaultFileUrl]]来使getFileUrl()在附件文件丢失时返回默认图像URL。

与Web表单一起使用

通常，ActiveRecord的文件通过Web界面使用文件上传机制进行设置。[[\yii2tech\ar\file\FileBehavior]]为所有者提供了一个特殊的虚拟属性，其名称由[[\yii2tech\ar\file\FileBehavior::fileAttribute]]确定。此属性可用于传递[[\yii\web\UploadedFile]]实例或本地文件名，这些文件应附加到ActiveRecord。此属性在所有者保存时进行处理，如果设置，将触发文件保存。例如

use yii\web\UploadedFile;

$model = Item::findOne(1);
$model->file = UploadedFile::getInstance($model, 'file');
$model->save();

var_dump($model->fileExists()); // outputs `true`

注意：不要在拥有者ActiveRecord类中声明 [[\yii2tech\ar\file\FileBehavior::fileAttribute]] 属性。确保它不会与任何现有拥有者字段或虚拟属性冲突。

如果 [[\yii2tech\ar\file\FileBehavior::autoFetchUploadedFile]] 已启用，行为将在拥有者保存之前自动获取上传的文件。

您可以在您的模型内部设置文件虚拟属性的验证规则，指定附加文件的类型、扩展名等限制。

class Item extends \yii\db\ActiveRecord
{
    public function rules()
    {
        return [
            // ...
            ['file', 'file', 'mimeTypes' => ['image/jpeg', 'image/pjpeg', 'image/png', 'image/gif'], 'skipOnEmpty' => !$this->isNewRecord],
        ];
    }
    // ...
}

在视图文件中，您可以使用属于拥有者模型的文件虚拟属性作为表单文件输入。

<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;

/* @var $model Item */
?>
<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]); ?>

<?= $form->field($model, 'name'); ?>
<?= $form->field($model, 'description'); ?>

<?= $form->field($model, 'file')->fileInput(); ?>

<div class="form-group">
    <?= Html::submitButton('Save', ['class' => 'btn btn-primary']) ?>
</div>

<?php ActiveForm::end(); ?>

在控制器中，您不需要任何特殊代码。

use yii\web\Controller;

class ItemController extends Controller
{
    public function actionCreate()
    {
        $model = new Item();

        if ($model->load(Yii::$app->request->post()) && $model->save()) {
            return $this->redirect(['view']);
        } else {
            return $this->render('create', [
                'model' => $model,
            ]);
        }
    }

    // ...
}

文件转换

直接保存文件并不总是足够的ActiveRecord附件。通常文件需要一些处理，例如图像缩放。

[[\yii2tech\ar\file\TransformFileBehavior]] 是为管理需要处理的文件（转换）而开发的 [[FileBehavior]] 的增强版本。您应该设置 [[\yii2tech\ar\file\TransformFileBehavior::transformCallback]] 来指定实际的文件处理算法，以及 [[\yii2tech\ar\file\TransformFileBehavior::fileTransformations]] 提供的命名处理及其特定设置。例如

use yii2tech\ar\file\TransformFileBehavior;
use yii\imagine\Image;

class Item extends \yii\db\ActiveRecord
{
    public function behaviors()
    {
        return [
            'file' => [
                'class' => TransformFileBehavior::className(),
                'fileStorageBucket' => 'item',
                'fileExtensionAttribute' => 'fileExtension',
                'fileVersionAttribute' => 'fileVersion',
                'transformCallback' => function ($sourceFileName, $destinationFileName, $options) {
                    try {
                        Image::thumbnail($sourceFileName, $options['width'], $options['height'])->save($destinationFileName);
                        return true;
                    } catch (\Exception $e) {
                        return false;
                    }
                },
                'fileTransformations' => [
                    'origin', // no transformation
                    'main' => [
                        'width' => 400,
                        'height' => 400,
                    ],
                    'thumbnail' => [
                        'width' => 100,
                        'height' => 100,
                    ],
                ],
            ],
        ];
    }
    // ...
}

在使用 [[\yii2tech\ar\file\TransformFileBehavior]] 方法 fileExists()、getFileContent() 和 getFileUrl() 时，第一个参数作为转换名称，返回该转换的结果。

$model = Item::findOne(1);
echo $model->getFileUrl('origin'); // outputs URL for the full-sized image
echo $model->getFileUrl('main'); // outputs URL for the medium-sized image
echo $model->getFileUrl('thumbnail'); // outputs URL for the thumbnail image

某些文件转换可能需要更改文件扩展名。例如：您可能希望将 *.psd 文件创建为 *.jpg 格式的预览。您可以使用 [[\yii2tech\ar\file\TransformFileBehavior::transformationFileExtensions]] 为每个转换指定文件扩展名。例如

use yii2tech\ar\file\TransformFileBehavior;
use yii\imagine\Image;

class Item extends \yii\db\ActiveRecord
{
    public function behaviors()
    {
        return [
            'file' => [
                'class' => TransformFileBehavior::className(),
                'fileTransformations' => [
                    'origin', // no transformation
                    'preview' => [
                        // ...
                    ],
                    'web' => [
                        // ...
                    ],
                ],
                'transformationFileExtensions' => [
                    'preview' => 'jpg',
                    'web' => function ($fileExtension) {
                        return in_array($fileExtension, ['jpg', 'jpeg', 'png', 'gif']) ? $fileExtension : 'jpg';
                    },
                ],
                // ...
            ],
        ];
    }
    // ...
}

您可能会遇到一些文件转换设置更改或新转换添加的问题，随着项目的演变，现有的保存文件会过时。在这种情况下，您可以使用 [[\yii2tech\ar\file\TransformFileBehavior::regenerateFileTransformations()]] 方法使用某些现有转换作为源来重新生成具有新设置的转换文件。例如

$model = Item::findOne(1);
$model->regenerateFileTransformations('origin'); // regenerate transformations using 'origin' as a source

图像文件转换

最常见的文件转换用例是图像缩放。因此，提供了一个特殊的行为 [[\yii2tech\ar\file\ImageFileBehavior]]。此行为通过 yiisoft/yii2-imagine 扩展提供图像缩放转换。配置示例

use yii2tech\ar\file\ImageFileBehavior;

class Item extends \yii\db\ActiveRecord
{
    public function behaviors()
    {
        return [
            'file' => [
                'class' => ImageFileBehavior::className(),
                'fileStorageBucket' => 'item',
                'fileExtensionAttribute' => 'fileExtension',
                'fileVersionAttribute' => 'fileVersion',
                'fileTransformations' => [
                    'origin', // no resize
                    'main' => [800, 600], // width = 800px, height = 600px
                    'thumbnail' => [100, 80], // width = 100px, height = 80px
                ],
            ],
        ];
    }
    // ...
}

注意：此包不包含 "yiisoft/yii2-imagine"，您需要自行安装。