README

yii2 的文件上传管理器，将 ActiveRecord 对象与文件和相册链接。

什么是文件上传管理器？

此模块为 ActiveRecord 添加了一个新的扩展，允许开发者将文件或其副本连接到另一个 ActiveRecord 对象。

由 Joseba Juániz 开发（@Patroklo）

西班牙语 Readme 版本

最低要求

Yii2
Php 5.4 或更高版本

未来计划

目前没有。

许可证

这是免费软件。它根据以下 BSD 许可证的条款发布。

以下条件满足时，允许重新分配和使用源代码和二进制形式，修改与否均可

源代码重新分配必须保留上述版权声明、本条件列表和以下免责声明。
二进制形式重新分配必须在文档和/或其他随分发提供的材料中重新生产上述版权声明、本条件列表和以下免责声明。
未经事先书面许可，Cyneek 的名称或其贡献者的名称不得用于认可或推广由此软件衍生出的产品。

安装

安装 Yii 2

通过 composer 安装包

  `"cyneek/yii2-fileupload": "dev-master", "coderfly/yii2-image": "@dev"`
   
  (I haven't managed to install the library in stable versions of Yii 2 because image library and the strange way of working composer has. If someone knows how to do it without adding this superfluous reference to the principal composer.json file, please tell :sweat_smile:).

更新配置文件 'config/web.php'

  	'modules' => [
  		'fileupload' => [
  			'class' => 'cyneek\yii2\fileupload\Module'
  		]
  		// set custom modules here
  	],

php yii migrate --migrationPath=@vendor/cyneek/yii2-fileupload/migrations

确保 PHP 可以写入您的 Yii 2 安装的 "web/" 目录。
大功告成！

定义

此库将允许用户通过扩展 FileModel.php 模型的对象上传或管理文件。此文件扩展了 ActiveRecord 并可用于数据库操作和网页表单。

这些对象必须链接到另一个对象，该对象将能够通过数据库操作获取所有链接到它的文件。

此包包含 2 个不同的模型

FileModel.php : 这是主要模型。所有文件对象都必须扩展此存档。为了正确使用它，开发人员必须填写一些基本的配置数据，这些数据将在下面的 Readme 中解释。
FileOwnerActiveRecord.php : 这是一个扩展了 ActiveRecord 的模型。它可以用于扩展具有与文件链接的对象。它提供了一种语法糖来检索与它们链接的一个或多个文件，并将这些对象链接到现有的文件对象。

该软件包使用“flysystem”库，允许用户通过ftp、dropbox等方式在本地服务器上操作文件，因此所有这些配置在FileUploader软件包中也都可能可用，以存储与对象链接的文件。鉴于每个扩展模型都可以有自己的配置，系统可以同时处理来自AmazonAWS、本地、ftp等文件。

文件上传软件包还使用了一个图像包，允许开发者在上传图像时使用GD或Imagick PHP库（取决于您的PHP安装）来管理图像尺寸、裁剪等。

设置文件模型

要使用该软件包，首先必须定义一个模型来管理一种类型的文件。每个这些对象模型将持有不同的文件，这些文件可以链接到任何系统模型对象。但首先必须做一些基本配置。

创建一个新的文件，其中包含扩展“FileModel”的类。
添加以下基本配置数据
- "default_values()"方法。必须在其内部返回一个包含“file_type”字符串的数组，该字符串不同于您在此Yii2安装中创建的任何其他FileModel，以及一个将定义文件存储目录的“upload_path”字符串。它不必是唯一的，但建议这样做。
例如
```
  return [
  	'file_type'	=> 'name_that_defines_the_model_in_the_database',
  	'upload_path'	=> 'path_where_files_will_be_stored'
  ];
```
此代码将创建与数据库中的“name_that_defines_the_model_in_the_database”字符串链接的文件对象，并将存储在“path_where_files_will_be_stored”目录路径中。请记住，在这个目录内部将会有一系列按“YYYY”/"MM"/"DD"定义的子文件夹，以便更整洁地存储文件。
- 可选参数“file_required”。它是一个布尔值，用于设置在Web表单中文件上传是否为必需。当其值为“False”时，Yii2不会在插入或更新操作中使表单的文件上传成为强制性的。默认值为TRUE。
- 可选方法"_copies_data()"。定义当调用"save()"方法时系统是否会对上传的文件进行复制。
例如
```
  return [
  		'operations' => [
  							['action' => 'resize', 
  							 'height' => '100', 
  							 'width' => 100, 
  							 'size' => 5000]
  						]
  		'file2' => [ more operations ]
  		];
```
此代码将创建一个上传文件的副本（应该是图像），将其调整到100x100像素大小，保持其比例（一个边不会正好是100像素），并将颜色质量降低，直到其重量达到5000字节。此外，包含操作数组的键将用于在"child_name"列中命名副本，这可以让开发者更容易地区分不同的文件。

例如

return 3;

也可以定义数字。在这种情况下，系统将创建3个确切的上传文件副本。

设置FileOwnerActiveRecord类型类

当与文件对象关联时，推荐使用扩展FileOwnerActiveRecord的对象，原因在于这个类提供了一系列帮助进行对象链接和访问其链接文件的方法。如果您想使用此库的另一种类型类，那么您将不得不为每个不同的类手动创建这些链接和访问。

要使用FileOwnerActiveRecord扩展对象，您必须

创建一个新的文件，其中包含扩展“FileOwnerActiveRecord”的类。

添加一个“linkedFiles()'方法，其中包含所有可能链接到该对象的文件的配置数组。

  protected function linkedFiles()
  {
  	return ['nameOfFieldToAccessFiles' => ExampleFileModel::className(),
  				'file' => AnotherFileModel::className()];
  }

重要提示：您不能在这个类中调用名为"getNameOfFieldToAccessFiles()"或"getFile()"的方法，因为系统将自动使用它们通过Yii2表之间的关系获取文件。

基本用法

一旦创建了文件模型，就是开始使用它的时候了。

将文件模型链接到所有者模型

当文件链接到另一个对象时，该对象被称为其“所有者”，因为现在它可以在任何时候访问所有文件。

处理这个问题最简单的方法是将另一个模型也扩展为 FileOwnerActiveRecord 类。这样，您可以使用附加到它的语法糖（请记住，它只是一个带有少量添加的 ActiveRecord 扩展）。

// we make a new empty file object
$file = new ExampleFileModel();
$file2 = new AnotherFileModel();

// get a loaded object from a class that extends FileOwnerActiveRecord
$object = new ImportantObject::findOne(1);

// file linked to object. This will be made into the database when launching a save() method for "$file". But remember that you can't save an empty file object.
$object->linkFile($file);
$object->linkFile($file2);

当对象不扩展 FileOwnerActiveRecord 类时，另一种创建链接的方式是

// we make a new empty file object
$file = new ExampleFileModel();
$file2 = new AnotherFileModel();

// get a loaded object from a class that **DOESN'T** extend FileOwnerActiveRecord
$object = new ImportantObject::findOne(1);

// Inverse linking a file with an object. 
$file->linkOwner($object);
$file2->linkOwner($object);

此外，如上所示，一个所有者可以同时链接来自不同类的不同文件对象类型。

访问链接到所有者对象的单个文件（仅适用于扩展 FileOwnerActiveRecord 的对象）

要访问链接到对象的单个文件（如果同时链接了多种类型的多个文件，则仅检索第一个），我们将使用它在类对象中定义的名称作为参数（就像在 Yii2 中处理数据库关系时一样）

// get a loaded object from a class that extends FileOwnerActiveRecord
$object = new ImportantObject::findOne(1);

$file = $object->nameOfFieldToAccessFilesOne;
$file2 = $object->fileOne;

还可以使用

// get a loaded object from a class that extends FileOwnerActiveRecord
$object = new ImportantObject::findOne(1);

$file = $object->nameOfFieldToAccessFiles;
$file2 = $object->file;

访问链接到所有者对象的全部文件（仅适用于扩展 FileOwnerActiveRecord 的对象）

这将获取一个包含所有链接到所有者对象的文件的对象数组

// get a loaded object from a class that extends FileOwnerActiveRecord
$object = new ImportantObject::findOne(1);

$file = $object->nameOfFieldToAccessFilesAll;
$file2 = $object->fileAll;

Yii 2 中的简单网页表单和文件上传

（请参阅示例目录）

多文件上传

由于有 "Filemanager::multiUpload" 方法，您可以与多文件上传库一起使用此库，该方法将返回一个数组，其中包含传递给作为参数的特定 FileModel 类的所有上传文件。

（请参阅示例目录获取更多信息）。

保存文件对象

除了从 ActiveRecord 类继承的 "save()" 方法外，还有一个名为 "saveAs" 的新方法，它将两个额外的参数放在原始的保存布尔参数之上

文件名

字符串，它将定义文件上传到其最终目的地后的文件名。请注意，使用此选项将覆盖之前存在的文件。

操作

一个数组，定义了对文件在插入/更新后将执行的操作。

自动文件操作

定义为复制操作或在 "saveAs" 方法中，这些是在插入/更新后更改文件的自动操作。

可以在同一文件中嵌套不同的操作。这允许开发人员通过将它们分成多个简单任务来执行更复杂的操作。

操作（字符串）（必需）
- resize
将图像调整到所选的尺寸（高度和宽度）
- crop
使用所选尺寸（高度、宽度、x起始点和y起始点）裁剪图像。如果没有定义起始点，则使用0,0。
- size
以降低质量的方式保存图像，以减少其重量。它将降低其质量，直到其大小小于定义的大小。
- crop_middle
仅裁剪图像的中间部分，只需要定义裁剪的高度和宽度。
height（整数）（可选）

以像素为单位定义图像调整大小和裁剪后的图像高度。

width（整数）（可选）

以像素为单位定义图像调整大小和裁剪后的图像宽度。

master（整数）（可选）

仅用于 resize 操作，定义图像如何调整大小：const NONE = 无约束 const WIDTH = 通过宽度减少 const HEIGHT = 通过高度减少 const AUTO = 最大减少 const INVERSE = 最小减少 const PRECISE = 不保持图像比例）

offset_x（整数）（可选）

定义系统开始裁剪图像的 x 轴起始点。

offset_y（整数）（可选）

定义系统开始裁剪图像的 y 轴起始点。

size（整数）（可选）

以字节为单位，定义图像可以具有的最大文件大小。如果它更大，则系统将降低其质量，直到它变得更小。

它们将定义为数组

  array['action'	=> 'resize',
 		'height'	=> NULL/pixels,
 		'width'		=> NULL/pixels,
  		'master'	=> NULL/int, (constrain reduction, defined like:
  									const NONE    = no constrain
									const WIDTH   = reduces by width
									const HEIGHT  = reduces by height
									const AUTO    = max reduction
									const INVERSE = minimum reduction
									const PRECISE = doesn't keep image ratio)
  		'offset_x'	=> NULL/int (offset for cropping only),
  		'offset_y'	=> NULL/int (offset for cropping only),
  		'size'		=> NULL/bytes
  	];

复制文件

也可以通过接受参数的方法makeCopy制作选定文件的副本。

操作（数组）（可选）

如前一点所述的文件操作。

child_name（字符串）（可选）

一个字符串，用于命名这个新副本。这将让开发者能够在每个文件中搜索特定的副本。

cyneek / yii2-fileupload

维护者

详情