README

Upload 插件 2.0

Upload 插件试图使用从 MeioUpload、UploadPack 和 PHP 文档等包中获得的技巧，以合理地上传文件。

背景

Media 插件太复杂了，合并 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 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关系是必要的。

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

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

替代行为

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

FileImportBehavior

FileImportBehavior可用于直接从磁盘导入文件。这对于从文件系统上的目录导入非常有用。

行为选项

pathMethod：用于文件路径的方法。此方法附加到下面的path选项
- 默认：(string) primaryKey
- 选项
  - flat：不为每个记录创建路径。文件被移动到'path'选项的值。
  - primaryKey：基于记录的primaryKey生成路径。在记录更新期间持续存在。
  - random：为每个文件上传生成随机路径。在记录更新期间不持续存在。
  - randomCombined：为每个文件上传生成随机路径 - 与模型ID组合 -。在记录更新期间不持续存在。
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} 都可用于命名，并将自动替换为实际术语。
- 注意：此外，文件扩展名也将自动添加。
- 注意：如果未指定，将根据 thumbnailPrefixStyle 的值设置为 {size}_{filename} 或 {filename}_{size}
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 更适用于 random 和 randomCombined 的 pathMethod，但在调整此选项时请记住这一点
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 像素

验证规则

默认情况下，模型不附加任何验证规则。如果需要，必须显式附加每个规则。不涉及 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'
	)
);