README

由 Allan Carvalho 提供

安装

1. 安装依赖项

您可以使用 composer 将此插件安装到您的 CakePHP 应用程序中。安装 composer 包的推荐方法是

composer require allanmcarvalho/upload

2. 加载插件

在 App\config\bootstrap.php

Plugin::load('Upload', ['bootstrap' => true]);

基本用法

1 - 您应该打开表，然后添加插件 Upload 的 behavior。

// in App\Model\Table\ExamplesTable.php
class ExamplesTable extends Table
{
...
    public function initialize(array $config)
    {
        parent::initialize($config);

        $this->addBehavior('Upload.Upload', [
			'file1' => [],
			'file2' => []
		]);
    }
...

注意：仅添加 Upload.Upload Behavior 并不意味着它已准备就绪，实际上，如果您只是添加，则不会发生任何事情。您必须定义哪些表列将负责存储文件名，如上所示（file1 和 file2）。

可用的 Behavior 设置

注意：配置名称必须与表列名称相同。在此示例中为 file1。

// in App\Model\Table\ExamplesTable.php
	
	$this->addBehavior('Upload.Upload', [
		'file1' => [
			'path' => WWW_ROOT . 'img' . DS,
			'prefix' => 'example_'
		]
	]);

选项

• path: 保存文件的路径。

注意：当未提供 path 时，默认为 WWW_ROOT . 'files' . DS . $this->table->getAlias() . DS 或当设置 image 设置时为 WWW_ROOT . 'img' . DS . $this->table->getAlias() . DS。

• prefix: 添加到图像文件名的前缀。默认：没有前缀；

• image: 图像上传的设置集；

// in App\Model\Table\ExamplesTable.php
	
	$this->addBehavior('Upload.Upload', [
		'file1'  => [
			'image'  => [
				'crop' => [
					'width' => 600 // Height will be the same
				],
				'format' => 'png',
				'quality' => 75, 
				'resize' => [
					'height' => 750, // width will be automatically calculated
				],
				'thumbnails' => [
					[
						'label' => 'thumb1',
						'resize' => [
							'height' => 750,
						],
						'watermark' => false // Disables watermark for this item
					],
					[
						'label' => 'thumb2',
						'resize' => [
							'min_size' => 750,
						],
						'watermark' => [
							'opacity' => 60, // 60% of opacity
							'position' => 'top', // center top position
							'path' => WWW_ROOT . 'img' . DS . 'watermark2.png',
						],
						'crop' => [
							'width' => 600 // Height will be the same 
						]
					]
				],
				'watermark' => [
					'ignore_default' => true, //do not insert watermark on default
					'opacity' => 10, // 10% of opacity
					'path' => WWW_ROOT . 'img' . DS . 'watermark.png',
					'position' => 'bottom-right'
				]
			]
		]
	]);

图像选项

注意：使用这些设置的兼容格式： jpg，png 和 gif。

• crop: （可选）裁剪图像。 注意：如果配置了调整大小，它将在裁剪之前执行。默认：没有裁剪； - width: （至少一个）裁剪图像的宽度。默认：如果设置了高度则相同； - height: （至少一个）裁剪图像的高度。默认：如果设置了宽度则相同； - x: （可选）基于左边的裁剪图像 x 位置。默认：居中； - y: （可选）基于顶部的裁剪图像 y 位置。默认：居中；

• format: 图像格式。可以是 (jpg，png，gif，same（与原始相同））。默认：jpg；
• quality: 从 1 到 100 的图像质量。默认：100；
• preserve_animation: 当图像为 gif 时，其动画不会被冻结。格式必须为 same。在此图像上不会进行任何更改（缩略图、裁剪...）。默认：false；
• resize: （可选）更改图像大小。默认：没有调整大小；
  • width: （至少一个）新图像宽度。默认：如果设置了高度则为自动；
  • height: （至少一个）新图像高度。默认：如果设置了宽度则为自动；
  • min_size: （至少一个）从较小的一侧调整图像大小。默认：false；
• thumbnails: （可选）设置以创建缩略图。默认：没有缩略图；
  • label: （必需）缩略图将保存的文件夹的标签。默认：没有标签；
  • resize: （可选）更改图像大小。默认：没有调整大小；
    • width: （至少一个）新图像宽度。默认：如果设置了高度则为自动；
    • height: （至少一个）新图像高度。默认：如果设置了宽度则为自动；
    • min_size: （至少一个）从较小的一侧调整图像大小。默认：false；
  • 水印: （可选）如果跟随着默认图片设置（如果存在）。如果为false则不插入水印。如果任何设置通过一个数组传入，将覆盖默认图片设置。默认：true；
    • 透明度: （可选）水印的透明度从1到100，数值越小越透明。默认：与原始相同。
    • 路径: （可选）此缩略图水印图片的路径。默认：与原始相同；
    • 位置: （可选）水印方向。默认：右下角。可以是以下相同的位置：
  • 裁剪: （可选）裁剪新的缩略图图片。注意：如果同时配置了调整大小，它将在裁剪之前完成。默认：没有；
    • 宽度: （必需）新图片裁剪宽度。默认：如果设置了高度则相同；
    • 高度: （必需）新图片裁剪高度。默认：如果设置了宽度则相同；
    • x: （必需）裁剪图片的x位置。默认：居中；
    • y: （必需）裁剪图片的y位置。默认：居中；
• 水印: 在图片上插入水印。默认：没有；
  • 忽略默认: （可选）如果为true，则忽略默认图片中的水印。默认：false；
  • 透明度: （可选）水印透明度从1到100，数值越小越透明。默认：100。
  • 路径: （必需）水印图片的路径。默认：没有；
  • 位置: （可选）水印方向。默认：右下角。可以是：
    • 左上角
    • 顶部
    • 右上角
    • 左边
    • 居中
    • 右边
    • 左下角
    • 底部
    • 右下角

####2 - 现在应该从表单打开视图并配置表单和输入为文件类型。

// in App\Template\Controller\add.ctp
...
	<?= $this->Form->create($example, ['type' => 'file']) ?>
	<?= $this->Form->control('title') ?>
	<?= $this->Form->control('file1', ['type' => 'file']) ?>
	<?= $this->Form->control('file2', ['type' => 'file']) ?>
    <?= $this->Form->button(__('Submit')) ?>
    <?= $this->Form->end() ?>
...

####3 - 删除文件而不删除实体

// in App\Controller\ExampleController.php
...
public function deleteFiles($id)
{
	$this->request->allowMethod(['post', 'delete']);
	$example = $this->Examples->get($id);
	if ($this->Examples->deleteFiles($example)) {
		$this->Flash->success(__('The files has been deleted.'));
	} else {
		$this->Flash->error(__('The files could not be deleted. Please, try again.'));
	}
	return $this->redirect(['action' => 'index']);
}
...

或

// in App\Controller\ExampleController.php
...
public function deleteFiles($id)
{
	$this->request->allowMethod(['post', 'delete']);
	$example = $this->Examples->get($id);
	if ($this->Examples->deleteFiles($example, ['file1'])) {
		$this->Flash->success(__('The files has been deleted.'));
	} else {
		$this->Flash->error(__('The files could not be deleted. Please, try again.'));
	}
	return $this->redirect(['action' => 'index']);
}
...

注意： deleteFiles($entity, $fields = []) 方法是行为添加的表方法，您甚至可以在 表 类中使用它。

####4 - 验证

有两种类型的验证器，一种用于验证文件信息，称为 UploadValidation，另一种是在添加更多功能后用于验证图片的 ImageValidation。您还可以通过调用 DefaultValidation 在一个中同时使用这两个。

// in App/Model/Table/ExampleTable.php
// Contain files validations
	public function validationDefault(Validator $validator)
	{
		$validator->setProvider('upload', \Upload\Validation\UploadValidation::class);

		$validator
			->add('file1', 'isUnderPhpSizeLimit', [
				'rule' => 'isUnderPhpSizeLimit', 
				'message' => 'Greater than the PHP size limit',
				'provider' => 'upload'
			]);
		
		$validator
			->add('file1', 'isUnderFormSizeLimit', [
				'rule' => 'isUnderFormSizeLimit',
				'message' => 'Greater than the FORM size limit',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isCompletedUpload', [
				'rule' => 'isCompletedUpload',
				'message' => 'Upload not completed',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isFileUpload', [
				'rule' => 'isFileUpload',
				'message' => 'File not uploaded',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isSuccessfulWrite', [
				'rule' => 'isSuccessfulWrite',
				'message' => 'Failed to write file',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isAboveMinSize', [
				'rule' => ['isAboveMinSize', 2048],
				'message' => 'Does not have the minimum required size',
				'provider' => 'upload'
			]);
		$validator
			->add('file1', 'isBelowMaxSize', [
				'rule' => ['isBelowMaxSize', 4096],
				'message' => 'Exceeds the maximum size',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isThisMimeType', [
				'rule' => ['isThisMimeType', ['image/jpeg', 'image/png']],
				'message' => 'File is not of the correct type',
                                'last'     => true,
				'provider' => 'upload'
			]);
	}

或

// in App/Model/Table/ExampleTable.php
// Contain image validations
	public function validationDefault(Validator $validator)
	{
		$validator->setProvider('upload', \Upload\Validation\ImageValidation::class);

		$validator
			->add('file1', 'isAboveMinWidth', [
				'rule' => ['isAboveMinWidth', 100], 
				'message' => 'Must have a wider width',
				'provider' => 'upload'
			]);
		
		$validator
			->add('file1', 'isBelowMaxWidth', [
				'rule' => ['isBelowMaxWidth', 900],
				'message' => 'Must have the shortest width',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isAboveMinHeight', [
				'rule' => ['isAboveMinHeight', 100],
				'message' => 'Must have a wider height',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isBelowMaxHeight', [
				'rule' => ['isBelowMaxHeight', 900],
				'message' => 'Must have the shortest height',
				'provider' => 'upload'
			]);

		$validator
			->add('file1', 'isThisWidth', [
				'rule' => ['isThisWidth', 800],
				'message' => 'Must have a width of 800px',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isThisHeight', [
				'rule' => ['isThisHeight', 900],
				'message' => 'Must have a height of 900px',
				'provider' => 'upload'
			]);

		$validator
			->add('file1', 'isThisWidthAndHeight', [
				'rule' => ['isThisWidthAndHeight', 800, 900],
				'message' => 'Must have a width of 800px and height of 900',
				'provider' => 'upload'
			]);
							
		$validator
			->add('file1', 'isThisAspectRatio', [
				'rule' => ['isThisAspectRatio', 3, 4],
				'message' => 'Wrong aspect ratio',
				'provider' => 'upload'
			]);
			
		$validator
			->add('file1', 'isThisExtension', [
				'rule' => ['isThisExtension', ['jpg', 'png']],
				'message' => 'Wrong image extension',
                                'last'     => true,
				'provider' => 'upload'
			]);
			
	}

或

// in App/Model/Table/ExampleTable.php
// Contains both validations
	public function validationDefault(Validator $validator)
	{
		$validator->setProvider('upload', \Upload\Validation\DefaultValidation::class);
		...
	}

####许可证: MIT