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 Submodule]

在您的 app 目录中输入

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

[GIT Clone]

在您的 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 文件中启用插件

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(); ?>

通过控制器进行程序性文件抓取

$data['photo'] = $image_url;
$this->User->set($data);
$this->User->save();

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

<?php
class User extends AppModel {
	public $actsAs = array(
		'Upload.Upload' => array(
			'photo' => array(
				'fields' => array(
					'dir' => 'photo_dir'
				),
				'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'
				),
				'thumbnailSizes' => array(
					'xvga' => '1024x768',
					'vga' => '640x480',
					'thumb' => '80x80'
				)
			)
		)
	);
}

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关系是必要的。

一旦您设置了所有上述内容，您就会有一个正常工作的多态上传！

请注意，这不是表示文件上传的唯一方式，但此处记录仅供参考。

替代行为

上传插件还包括一个FileImport行为和一个FileGrabber行为。

FileImportBehavior

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

行为选项

pathMethod：用于文件路径的方法。此方法附加到下面的path选项
- 默认：(string) primaryKey
- 选项
  - flat：不会为每条记录创建路径。文件被移动到'path'选项的值。
  - primaryKey：基于记录的primaryKey生成路径。在记录更新后保持不变。
  - random：为每个文件上传生成随机路径，形式为nn/nn/nn，其中nn是随机数字。在记录更新后不会保持不变。
  - randomCombined：为每个文件上传生成带有模型ID的随机路径，形式为ID/nn/nn/nn，其中ID是当前模型ID，nn是随机数字。在记录更新后不会保持不变。
path：相对于 APP_PATH 的路径。应以 {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} 和 {filename} 都可用于命名，并将自动替换为实际术语。
- 注意：此外，文件扩展名将自动添加。
- 注意：如果未指定，将设置为 {size}_{filename} 或 {filename}_{size}，具体取决于 thumbnailPrefixStyle 的值
thumbnailPath：缩略图保存的相对于 rootDir 的路径。应以 {DS} 结尾。如果未设置，缩略图将保存在 path。
- 默认值：NULL
- 占位符
  - {ROOT}：由 rootDir 选项替换
  - {DS}：由 DIRECTORY_SEPARATOR 替换
  - {model}：由模型别名替换
  - {field}：由字段名替换
  - {size}：由给定的 thumbnailSize 中指定的尺寸键替换
  - {geometry}：由给定的 thumbnailSize 中指定的几何值替换
thumbnailPrefixStyle：是否将样式前缀或后缀添加到缩略图上
- 默认值：（布尔值）true 前缀缩略图
- 注意：当在您的配置中未指定 thumbnailName 时，此选项会覆盖 thumbnailName
thumbnailQuality：生成的缩略图的质量，范围从 0-100。使用 GD 进行图像处理时，不支持 gif 图像。
- 默认值：（整数）75
thumbnailSizes：缩略图尺寸数组，尺寸名称映射到几何形状
- 默认值：（数组）空
thumbnailType：覆盖生成的缩略图类型
- 默认值：（混合型）false 或当上传是媒体文件时为 png
- 选项
  - 任何有效的图像类型
mediaThumbnailType：覆盖非图像媒体（pdfs）生成的缩略图类型。覆盖thumbnailType
- 默认：（混合）png
- 选项
  - 任何有效的图像类型
saveDir：可以用来关闭保存目录
- 默认值：（布尔值）true
- 注意：由于保存目录的方式，如果你使用除了平坦以外的pathMethod，并且将saveDir设置为false，你可能会遇到无法预测的文件位置。这比primaryKey对pathMethod为random和randomCombined的问题更大，但在调整此选项时请记住这一点
mode：为创建的上传目录设置的UNIX权限。
- 默认：（整数）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指定的最大文件大小

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

isUnderFormSizeLimit

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

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

isCompletedUpload

检查文件是否已完全上传

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

isFileUpload

检查是否上传了文件

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

isFileUploadOrHasExistingValue

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

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

tempDirExists

检查PHP临时目录是否缺失

public $validate = array(
	'photo' => array(
		'rule' => 'tempDirExists',
		'message' => 'The system temporary directory is missing'
	)
);

如果传递了参数$requireUpload，则在文件未上传时可以跳过此检查

public $validate = array(
	'photo' => array(
		'rule' => array('tempDirExists', false),
		'message' => 'The system temporary directory is missing'
	)
);