README

上传插件 2.0

上传插件试图使用诸如 MeioUpload 、 UploadPack 和 PHP 文档等技术来理智地上传文件。

背景

媒体插件过于复杂，将最新更新合并到 MeioUpload 中也是一个大麻烦，因此我在这里又构建了一个上传插件。我会在一个月后构建另一个，并称之为 "YAUP"。

要求

CakePHP 2.x
Imagick/GD PHP 扩展（用于创建缩略图）
PHP5
耐心

安装

[使用 Composer]

在 Packagist 上查看，并将最新版本的 json 片段复制到您的项目的 composer.json 文件中。例如，v. 1.0.0 将看起来像这样

{
	"require": {
		"josegonzalez/cakephp-upload": "1.0.0"
	}
}

因为此插件在其自己的 composer.json 中设置了类型 cakephp-plugin，所以 composer 知道将其安装到您的 /Plugins 目录中，而不是在通常的 vendors 文件中。建议您将 /Plugins/Upload 添加到您的 .gitignore 文件中。（为什么？阅读此内容。）

[手动]

下载此文件：http://github.com/josegonzalez/cakephp-upload/zipball/master
解压下载内容。
将生成的文件夹复制到 app/Plugin
将您刚刚复制的文件夹重命名为 Upload

[GIT 子模块]

在您的应用目录中键入

git submodule add -b master git://github.com/josegonzalez/cakephp-upload.git Plugin/Upload
git submodule init
git submodule update

[GIT 克隆]

在您的 Plugin 目录中键入

git clone -b master git://github.com/josegonzalez/cakephp-upload.git Upload

Imagick 支持

要启用 Imagick 支持，您需要安装 imagick

# Debian systems
sudo apt-get install php-imagick

# OS X Homebrew
brew tap homebrew/dupes
brew tap josegonzalez/homebrew-php
brew install php54-imagick

# From pecl
pecl install imagick

如果您无法安装 imagick，请不要使用 imagick，而是在设置选项中将插件配置为 'thumbnailMethod' => 'php'。

启用插件

在 2.0 中，您需要在您的 app/Config/bootstrap.php 文件中启用插件

<?php
CakePlugin::load('Upload');
?>

如果您已经使用 CakePlugin::loadAll();，则此步骤不是必需的。

用法

CREATE table users (
	id int(10) unsigned NOT NULL auto_increment,
	username varchar(20) NOT NULL,
	photo varchar(255)
);

<?php
class User extends AppModel {
	public $actsAs = array(
		'Upload.Upload' => array(
			'photo'
		)
	);
}
?>

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
<?php echo $this->Form->input('User.username'); ?>
<?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
<?php echo $this->Form->end(); ?>

使用上述设置，上传的文件无法删除。为此，必须添加一个字段来存储文件的目录，如下所示

CREATE table users (
	`id` int(10) unsigned NOT NULL auto_increment,
	`username` varchar(20) NOT NULL,
	`photo` varchar(255) DEFAULT NULL,
	`photo_dir` varchar(255) DEFAULT NULL,
	PRIMARY KEY (`id`)
);

<?php
class User extends AppModel {
	public $actsAs = array(
		'Upload.Upload' => array(
			'photo' => array(
				'fields' => array(
					'dir' => 'photo_dir'
				)
			)
		)
	);
}
?>

在上面的示例中，photo 可以是通过表单中的文件输入进行文件上传，或通过文本输入从 URL 获取文件抓取器，或者在没有表单的情况下通过控制器程序化地通过 URL 获取文件。

文件上传示例

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
	<?php echo $this->Form->input('User.username'); ?>
	<?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
	<?php echo $this->Form->input('User.photo_dir', array('type' => 'hidden')); ?>
<?php echo $this->Form->end(); ?>

通过表单进行文件抓取示例

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
	<?php echo $this->Form->input('User.username'); ?>
	<?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
	<?php echo $this->Form->input('User.photo_dir', array('type' => 'hidden')); ?>
<?php echo $this->Form->end(); ?>

不带表单的程序化文件检索

<?php
$this->User->set(array('photo' => $image_url));
$this->User->save();
?>

创建缩略图

缩略图不会自动创建。要创建缩略图，必须定义缩略图大小：注意：默认情况下，缩略图将通过 imagick 生成，如果您想使用 GD，您需要设置 thumbnailMethod 属性。例如：'thumbnailMethod' => 'php'。

<?php
class User extends AppModel {
	public $actsAs = array(
		'Upload.Upload' => array(
			'photo' => array(
				'thumbnailSizes' => array(
					'xvga' => '1024x768',
					'vga' => '640x480',
					'thumb' => '80x80'
				)
			)
		)
	);
}
?>

上传多个文件

也可以将多个文件附加到单个记录中

<?php
class User extends AppModel {
	public $actsAs = array(
		'Upload.Upload' => array(
			'resume',
			'photo' => array(
				'fields' => array(
					'dir' => 'profile_dir'
				)
			)
		)
	);
}
?>

Upload.Upload 数组中的每个键都是字段名称，并且可以包含自己的配置。例如，您可能想要为存储文件路径设置不同的字段

<?php
class User extends AppModel {
	public $actsAs = array(
		'Upload.Upload' => array(
			'resume' => array(
				'fields' => array(
					'dir' => 'resume_dir',
					'type' => 'resume_type',
					'size' => 'resume_size',
				)
			),
			'photo' => array(
				'fields' => array(
					'dir' => 'photo_dir',
					'type' => 'photo_type',
					'size' => 'photo_size',
				)
			)
		)
	);
}
?>

请注意，尽管此插件在每次请求上传文件的数量方面没有限制，但您应该将其保持在较低水平，以降低用户阻塞其他请求的能力。

PDF支持

现在可以为PDF文件的第一页生成缩略图。（仅适用于imagick的thumbnailMethod。）

有关如何配置此插件的详细信息，请参阅行为选项。

使用多态附件模型进行文件存储

在某些情况下，您可能希望为多个模型存储多个文件上传，但出于某种原因不希望使用多个表。例如，我们可能有一个可以拥有多个图像的画廊的Post模型，以及一个拥有多个视频的Message模型。在这种情况下，我们将使用一个Attachment模型

Post hasMany Attachment

我们可以为Attachment模型使用以下数据库模式

CREATE table attachments (
	`id` int(10) unsigned NOT NULL auto_increment,
	`model` varchar(20) NOT NULL,
	`foreign_key` int(11) NOT NULL,
	`name` varchar(32) NOT NULL,
	`attachment` varchar(255) NOT NULL,
	`dir` varchar(255) DEFAULT NULL,
	`type` varchar(255) DEFAULT NULL,
	`size` int(11) DEFAULT 0,
	`active` tinyint(1) DEFAULT 1,
	PRIMARY KEY (`id`)
);

因此，我们的附件记录将能够有一个名称，并且可以随时激活/停用。该方案只是一个示例，并且此类功能需要在您的应用程序中实现。

一旦创建了attachments表，我们将创建以下模型

<?php
class Attachment extends AppModel {
	public $actsAs = array(
		'Upload.Upload' => array(
			'attachment' => array(
				'thumbnailSizes' => array(
					'xvga' => '1024x768',
					'vga' => '640x480',
					'thumb' => '80x80',
				),
			),
		),
	);

	public $belongsTo = array(
		'Post' => array(
			'className' => 'Post',
			'foreignKey' => 'foreign_key',
		),
		'Message' => array(
			'className' => 'Message',
			'foreignKey' => 'foreign_key',
		),
	);
}
?>

我们还需要在Post模型中提供一个有效的反关系

<?php
class Post extends AppModel {
	public $hasMany = array(
		'Image' => array(
			'className' => 'Attachment',
			'foreignKey' => 'foreign_key',
			'conditions' => array(
				'Image.model' => 'Post',
			),
		),
	);
}
?>

这里需要注意的关键点是Post模型对与Attachment模型的关系有一些条件，其中Image.model必须是Post。请记住将model字段设置为Post或您想要附加到的任何模型，否则在执行查找查询时可能会得到错误的关系结果。

我们还需要在我们的Message模型中有一个类似的关系

<?php
class Message extends AppModel {
	public $hasMany = array(
		'Video' => array(
			'className' => 'Attachment',
			'foreignKey' => 'foreign_key',
			'conditions' => array(
				'Video.model' => 'Message',
			),
		),
	);
}
?>

现在我们已经设置了模型，我们应该在我们的控制器中创建适当的操作。为了使内容简短，我们仅记录Post模型

<?php
class PostsController extends AppController {
	/* the rest of your controller here */
	public function add() {
		if ($this->request->is('post')) {
			try {
				$this->Post->createWithAttachments($this->request->data);
				$this->Session->setFlash(__('The message has been saved'));
			} catch (Exception $e) {
				$this->Session->setFlash($e->getMessage());
			}
		}
	}
}
?>

在上面的示例中，我们正在调用Post模型的自定义createWithAttachments方法。这将允许我们将Post创建逻辑统一在一个地方。该方法概述如下

<?php
class Post extends AppModel {
	/* the rest of your model here */

	public function createWithAttachments($data) {
		// Sanitize your images before adding them
		$images = array();
		if (!empty($data['Image'][0])) {
			foreach ($data['Image'] as $i => $image) {
				if (is_array($data['Image'][$i])) {
					// Force setting the `model` field to this model
					$image['model'] = 'Post';

					// Unset the foreign_key if the user tries to specify it
					if (isset($image['foreign_key'])) {
						unset($image['foreign_key']);
					}

					$images[] = $image;
				}
			}
		}
		$data['Image'] = $images;

		// Try to save the data using Model::saveAll()
		$this->create();
		if ($this->saveAll($data)) {
			return true;
		}

		// Throw an exception for the controller
		throw new Exception(__("This post could not be saved. Please try again"));
	}
}
?>

上面的模型方法将

确保我们只尝试保存有效的图像
强制外键为未指定。这将允许saveAll正确关联它
强制模型字段为Post

现在设置好了，我们只需要为我们的控制器创建一个视图。以下是一个View/Posts/add.ctp的示例视图（省略了示例中不需要的字段）

<?php
	echo $this->Form->create('Post', array('type' => 'file'));
	echo $this->Form->input('Image.0.attachment', array('type' => 'file', 'label' => 'Image'));
	echo $this->Form->input('Image.0.model', array('type' => 'hidden', 'value' => 'Post'));
	echo $this->Form->end(__('Add'));
?>

您会发现的一个重要的事情是我没有将Attachment模型称为Attachment，而是称为Image；当我最初指定一个Attachment和Post之间的$hasMany关系时，我将Attachment别名为Image。这是在您的许多多态模型之间相互关联的情况下所必需的，作为一种向CakePHP ORM提供正确引用模型数据的提示。

我还使用了Model.{n}.field记法，这允许您将多个附件记录添加到Post中。这对于我们在此示例中使用的$hasMany关系是必需的。

一旦您拥有了上述所有内容，您将拥有一个工作的多态上传！

请注意，这并不是表示文件上传的唯一方法，但这里记录下来供参考。

其他行为

Upload插件还附带了一个FileImport行为和一个FileGrabber行为。

FileImportBehavior

FileImportBehavior可用于直接从磁盘导入文件。这对于从已存在于文件系统中的目录导入是有用的。

行为选项

pathMethod：用于文件路径的方法。此方法附加到下面的path选项
- 默认值：（字符串）primaryKey
- 选项
  - flat：不为每条记录创建路径。文件被移动到'path'选项的值。
  - primaryKey：基于记录的primaryKey生成路径。在记录更新期间持久化。
  - random：为每个文件上传生成随机路径，格式为nn/nn/nn，其中nn是随机数字。不会在记录更新后持久化。
  - randomCombined：为每个文件上传生成带模型ID的随机路径，格式为ID/nn/nn/nn，其中ID是当前模型的ID，nn是随机数字。不会在记录更新后持久化。
path：相对于rootDir的路径。应以{DS}结尾
- 默认值：（字符串）'{ROOT}webroot{DS}files{DS}{model}{DS}{field}{DS}'
- 占位符
  - {ROOT}：由rootDir选项替换
  - {DS}：由DIRECTORY_SEPARATOR替换
  - {model}：由模型别名替换
  - {field}：由字段名替换
  - {primaryKey}：当存在时，由记录主键替换。如果用于创建新记录，将具有未定义的行为。
  - {size}：当用于常规文件上传路径时，由空字符串替换（空字符串）。仅对调整大小后的缩略图可用。
  - {geometry}：当用于常规文件上传路径时，由空字符串替换（空字符串）。仅对调整大小后的缩略图可用。
fields：上传文件时使用的字段数组
- 默认值：（数组）array('dir' => 'dir', 'type' => 'type', 'size' => 'size')
- 选项
  - dir：用于存储目录的字段
  - type：用于存储文件类型的字段
  - size：用于存储文件大小的字段
rootDir：移动图像的根目录。当需要时自动添加到path和thumbnailPath
- 默认值（字符串）ROOT . DS . APP_DIR . DS
mimetypes：用于验证的mimetypes数组
- 默认值：（数组）空
extensions：用于验证的扩展名数组
- 默认值：（数组）空
maxSize：验证的最大文件大小（字节）
- 默认值：（整数）2097152
minSize：验证的最小文件大小（字节）
- 默认值：（整数）8
maxHeight：验证的最大图像高度
- 默认值：（整数）0
minHeight：验证的最小图像高度
- 默认值：（整数）0
maxWidth：验证的最大图像宽度
- 默认值：（整数）0
minWidth：验证的最小图像宽度
- 默认值：（整数）0
deleteOnUpdate：在上传新版本时是否删除文件（由于命名冲突可能具有危险性）
- 默认值：（布尔值）false
thumbnails：是否创建缩略图
- 默认值：（布尔值）true
thumbnailMethod：用于调整缩略图大小的方法
- 默认值：（字符串）imagick
- 选项
  - imagick：使用PHP imagick扩展生成缩略图
  - php：使用内置的PHP方法（GD扩展）生成缩略图。不支持BMP图像。
thumbnailName：缩略图的命名风格
- 默认值：NULL
- 注意：占位符{size}、{geometry}和{filename}用于命名，并将自动替换为实际术语。
- 注意：此外，将自动添加文件扩展名。
- 注意：如果未指定，将根据thumbnailPrefixStyle的值设置为{size}_{filename}或{filename}_{size}
thumbnailPath：缩略图保存的相对rootDir的路径。应以{DS}结尾。如果未设置，缩略图将保存在path中。
- 默认值：NULL
- 占位符
  - {ROOT}：由rootDir选项替换
  - {DS}：由DIRECTORY_SEPARATOR替换
  - {model}：由模型别名替换
  - {field}：由字段名替换
  - {size}：由给定的thumbnailSize指定的size键替换
  - {geometry}：由给定的thumbnailSize指定的geometry值替换
thumbnailPrefixStyle：是否将样式前缀或后缀添加到缩略图上
- 默认值：（布尔值）true 前缀缩略图
- 注意：当在配置中未指定thumbnailName时，这将覆盖thumbnailName。
thumbnailQuality：生成的缩略图质量，范围是0-100。使用GD进行图像处理时，不支持gif图像。
- 默认值：(int) 75
thumbnailSizes：缩略图尺寸数组，尺寸名称映射到几何形状
- 默认值：（数组）空
thumbnailType：覆盖生成的缩略图类型
- 默认值：(mixed) false 或当上传是媒体文件时为png
- 选项
  - 任何有效的图像类型
mediaThumbnailType：覆盖非图像媒体（pdfs）生成的缩略图类型。覆盖thumbnailType
- 默认值：(mixed) png
- 选项
  - 任何有效的图像类型
saveDir：可用于关闭保存目录
- 默认值：（布尔值）true
- 注意：由于保存目录的方式，如果你使用除平坦以外的pathMethod，并将saveDir设置为false，你可能会陷入无法预测文件位置的困境。这比primaryKey对于pathMethod为random和randomCombined更成问题，但当你调整此选项时请记住这一点
mode：设置在创建上传目录时的UNIX权限。
- 默认值：(integer) 0777

缩略图尺寸和样式

样式是定义将生成的原始图像缩略图的定义。你可以定义任意多个。

<?php
class User extends AppModel {
	public $name = 'User';
	public $actsAs = array(
		'Upload.Upload' => array(
			'photo' => array(
				'thumbnailSizes' => array(
					'big' => '200x200',
					'small' => '120x120'
					'thumb' => '80x80'
				)
			)
		)
	);
}
?>

样式仅适用于以下类型的图像

image/bmp
image/gif
image/jpeg
image/pjpeg
image/png
image/vnd.microsoft.icon
image/x-icon

你可以为你的尺寸指定以下任何缩放模式

100x80 - 调整尺寸以最佳适应这些维度，如果原始纵横比不同，则修剪重叠的边缘
[100x80] - 调整尺寸以适应这些维度，如果原始纵横比不同，则添加白色条纹
100w - 保持原始纵横比，调整到100像素宽
80h - 保持原始纵横比，调整到80像素高
80l - 保持原始纵横比，调整到最长边为80像素
600mw - 保持原始纵横比，调整到最大600像素宽，如果原始图像小于600像素宽，则复制原始图像
800mh - 保持原始纵横比，调整到最大800像素高，如果原始图像小于800像素高，则复制原始图像
960ml - 保持原始纵横比，调整到最长边最大960像素，如果缩略图比原始图像大，则复制原始图像

验证规则

默认情况下，模型不附加任何验证规则。如果需要，必须明确附加每个规则。不涉及PHP上传错误的规则可配置，但回退到行为配置。

isUnderPhpSizeLimit

检查文件是否不超过PHP指定的最大文件大小

<?php
public $validate = array(
	'photo' => array(
		'rule' => 'isUnderPhpSizeLimit',
		'message' => 'File exceeds upload filesize limit'
	)
);
?>

isUnderFormSizeLimit

检查文件是否不超过HTML表单指定的最大文件大小

<?php
public $validate = array(
	'photo' => array(
		'rule' => 'isUnderFormSizeLimit',
		'message' => 'File exceeds form upload filesize limit'
	)
);
?>

isCompletedUpload

检查文件是否已完全上传

<?php
public $validate = array(
	'photo' => array(
		'rule' => 'isCompletedUpload',
		'message' => 'File was not successfully uploaded'
	)
);
?>

isFileUpload

检查是否上传了文件

<?php
public $validate = array(
	'photo' => array(
		'rule' => 'isFileUpload',
		'message' => 'File was missing from submission'
	)
);
?>

isFileUploadOrHasExistingValue

检查是否已上传文件，或者数据库中的现有值不为空

<?php
public $validate = array(
	'photo' => array(
		'rule' => 'isFileUploadOrHasExistingValue',
		'message' => 'File was missing from submission'
	)
);
?>