README

此文件有俄语版本 README_RU.md.

关于模块

此模块旨在解决在Yii2框架的ActiveRecord模型中创建文件字段的问题。模块的主要组件包括

floor12\files\components\FileBehaviour - 必须连接到ActiveRecord模型的属性
floor12\files\components\FileInputWidget - 一个InputWidget，允许添加、编辑和通常处理文件
floor12\files\components\FileListWidget - 一个额外的组件，用于显示文件列表，具有在Lightbox2画廊中查看图像、以zip格式下载当前字段的所有文件和使用Microsoft office online查看Word和Excel文件的能力

主要功能

向ActiveRecord模型添加一个或多个带文件的字段
使用在rules()部分中定义的标准FileValidator设置这些字段的验证
在处理图像时，可以配置图像比例（在这种情况下，通过FileInputWidget组件加载图像时将自动打开一个模态窗口以裁剪图像到所需的比例）
创建具有最佳大小的缩略图，以适应每种情况的网站模板。这些缩略图还支持WEBP格式
以ZIP格式下载文件
FileInputWidget支持通过拖放更改文件顺序、裁剪和更新文件名
在拖放上传的情况下，文件结果文件顺序与客户端文件夹中的顺序相同
通过EXIF标签自动检测水平方向
如果您需要通过网站的网络界面之外，使用控制台解析器和其他类似情况将图像添加到模型中，这是可能的。为此，模块包括两个类：FileCreateFromInstance和FileCreateFromPath，这些类可以帮助从服务器文件系统将文件添加到AR模型中
对于视频文件：使用ffmpeg工具将其重新编码为h264

i18n

目前，该模块支持以下语言

英语
俄语

工作原理

所有文件数据都存储在file表中。通过三个字段与模型关联的file模型

class - 中继模型的完整类名
field - 模型字段的名称
object_id - 模型的主键

当文件添加到表单时，它会在后台上传到服务器，所有处理都在那里进行。处理完成后，它将被写入磁盘，并在file表中为它创建一个新的条目，其中class和field字段填充了来自模型的数据，而object_id为空，只有在ActiveRecord模型保存后才会分配。当从组件中删除文件时，它不会从磁盘或file表中删除，只是object_id等于0。您可以使用控制台命令files / console / clean定期清理这种类型的孤儿文件。

安装和配置

要将此模块添加到您的应用程序，只需运行

$ composer require floor12/yii2-module-files

或将其添加到您的composer.json中的require部分。

"floor12/yii2-module-files": "dev-master"

然后执行迁移以创建file表。

$ ./yii migrate --migrationPath=@vendor/floor12/yii2-module-files/src/migrations/

之后，将模块数据包含在应用配置的modules部分

'modules' => [
            'files' => [
                'class' => 'floor12\files\Module',
                'storage' => '@app/storage',
                'cache' => '@app/storage_cache',
                'token_salt' => 'some_random_salt',
            ],
        ],
    ...

要设置的参数

storage - 存储文件和图片源的文件夹的路径别名，默认情况下位于项目根目录中的storage文件夹；
cache - 创建和缓存模块即时请求的图片缩略图的文件夹的路径别名；
token_salt - 用于生成InputWidget令牌的唯一盐值。

使用方法

与ActiveRecord模型一起工作

要将一个或多个文件字段添加到ActiveRecord模型中，需要将其与floor12\files\components\FileBehaviour连接，并传递一个字段名列表，该列表将在模型中存储文件。例如，对于User模型，这里定义了2个文件字段：avatar和documents

 public function behaviors()
 {
     return [
         'files' => [
             'class' => 'floor12\files\components\FileBehaviour',
             'attributes' => [
                 'avatar',
                 'documents'
             ],
         ],
         ...

为了在表单中显示漂亮的属性标签，请向attributeLabels()添加一些标签

 public function attributeLabels()
    {
        return [
            ...
            'avatar' => 'Аватар',
            'documents' => 'Документы',
            ...
        ];
    }

在ActiveRecord模型的rules()方法中设置验证规则

public function rules()
{
    return [
        // Avatar is required attribute 
        ['avatar', 'required'],
        
        // Avatar allow to uploade 1 file with this extensions: jpg, png, jpeg, gif
        ['avatar', 'file', 'extensions' => ['jpg', 'png', 'jpeg', 'gif'], 'maxFiles' => 1], 

        // Documens allows to upload a few files with this extensions: docx, xlsx
        ['documents', 'file', 'extensions' => ['docx', 'xlsx'], 'maxFiles' => 10],
    ...

与文件一起工作

如果FileValidator中的maxFiles等于1，则此属性将存储一个floor12\files\models\File对象。示例

// The href field contains web path to file source
echo Html::img($model->avatar->href)     

// __toString() method of File object will return href as well
echo Html::img($model->avatar)

如果文件是图像，getPreviewWebPath方法返回图像缩略图的web路径。默认情况下，缩略图以jpeg或png格式创建，这取决于源文件。但也可以使用WEBP选项。

File::getPreviewWebPath(int $width = 0, int $height = 0 ,bool $webp = false)

使用示例

// User avatar thumbnail with 200px width 
echo Html::img($model->avatar->getPreviewWebPath(200));     

// User avatar thumbnail with 200px width  and WEBP format
echo Html::img($model->avatar->getPreviewWebPath(200, 0, true));

当maxFiles等于1时，可以启用多文件上传。在这种情况下，模型字段将包含一个包含floor12\files\models\File对象的数组

foreach ($model->docs as $doc}
    Html::a($doc->title, $doc->href);

这里还有一个示例，展示了缩略图的高级使用。在这种情况下，我们使用现代的picture和source标签，以及媒体查询。结果，我们有了8个不同的缩略图：4个为支持WEBP格式的浏览器提供WEBP格式，4个为jpeg格式。具有视网膜显示的设备将获得双倍分辨率的图像，普通屏幕有常规尺寸的图片。此示例还使用不同屏幕宽度下的不同图像宽度（仅作为移动/桌面图像切换的示例）

<picture>
    <source type="image/webp" media='(min-width: 500px)' srcset="
                             <?= $model->poster->getPreviewWebPath(150, true) ?> 1x,
                             <?= $model->poster->getPreviewWebPath(300, true) ?> 2x">
    <source type="image/webp" media='(max-width: 500px)' srcset="
                             <?= $model->poster->getPreviewWebPath(350, true) ?> 1x,
                             <?= $model->poster->getPreviewWebPath(700, true) ?> 2x">
    <source type="image/jpeg" media='(min-width: 500px)' srcset="
                             <?= $model->poster->getPreviewWebPath(150, false) ?> 1x,
                             <?= $model->poster->getPreviewWebPath(300, false) ?> 2x">
    <img src="<?= $model->poster->getPreviewWebPath(150) ?>" 
         srcset=" 
               <?= $model->poster->getPreviewWebPath(350) ?> 1x, 
               <?= $model->poster->getPreviewWebPath(700) ?> 2x"
         alt="<?= $model->title ?>">
</picture>

图片标签小部件

如果对象类型为File是图像（$file->isImage() === true），则可以使用PictureWidget。此小部件有助于生成html标签

echo PictureWidget::widget([
    'model' => $file,
    'alt' => 'Some alternative text',
    'width' => 100
]);

这将生成以下html

<picture>
    <source type="image/webp"
            srcset="/imageurl/image1xWebp 1x,/imageurl/image2xWebp 2x">
    <img src="/imageurl/image 1x"
         srcset="/imageurl/image 1x,/imageurl/image 2x"
         alt="<?= $model->title ?>">
</picture>

允许传递媒体查询到小部件的附加参数。

列出文件

有一个用于列出所有文件的小部件。它支持Lightbox2画廊来显示图像和MS Office文件的预览。它还支持将附加到字段的文件下载为ZIP存档。

echo \floor12\files\components\FileListWidget::widget([
   'files' => $model->docs, 
   'downloadAll' => true, 
   'zipTitle' => "Documents of {$user->fullname}" 
])

必须将File对象数组传递到小部件的files字段。另外还有一些额外的参数可用

title - 可选地设置块标题（默认情况下，它从AttributeLabels()中获取）",
downloadAll - 显示“全部下载”按钮，
zipTitle - 设置ZIP存档的文件名，
passFirst - 跳过数组中的第一个文件（通常需要在不显示第一张图片的情况下显示画廊。例如，在新闻视图页面上，第一张图片用作新闻主图片时）。

ActiveForm的InputWidget

要在您的表单中显示文件块，请使用floor12\files\components\FileInputWidget

<?= $form->field($model, 'avatar')->widget(floor12\files\components\FileInputWidget::class) ?>

此外，如果FileValidator中的maxFiles参数等于1或更多，则FileInputWidget将加载一个表单来加载一个或多个文件。如果需要，可以将uploadButtonText和uploadButtonClass参数传递给小部件。

贡献

我很乐意在模块的开发、支持和错误报告中获得任何帮助。

floor12 / yii2-module-files

维护者

详情