README

文件上传管理模板让你头疼吗？你想简化修改和缓存原始上传文件的过程吗？Phperclip 是一个用于简化文件存储、排序和处理的软件包。

功能

• 通过界面和一个可选的特质将文件附加到任何 eloquent 模型
• 可配置和可定制的存储驱动程序
• 根据所使用的存储驱动程序生成文件的 URI
• 通过 FileProcessors 插件处理文件。
• 通过内置的 FileProcessor 进行图像处理。
• 强大的、无差别的批量处理器

设置

要将 Phperclip 设置好以便在项目中使用，请遵循设置 Laravel 4 软件包的常规步骤。

• 将 bmartel/phperclip 添加到您的 composer.json 文件中。
• 在项目根目录下运行 composer update。
• 编辑您的 app/config/app.php 文件并添加以下内容：
  • 'Bmartel\Phperclip\ServiceProvider', 到 providers 数组中
  • 'Phperclip' => 'Bmartel\Phperclip\Facade', 到 aliases 数组中
• 运行迁移 ./artisan migrate --package="bmartel/phperclip"。
• 复制配置 ./artisan config:publish bmartel/phperclip。

Note: If you are using type-hinted dependency injection in your project, as a convenience Phperclip binds the type `Bmartel\Phperclip\Service` in the container.

配置

文件名生成

文件名使用注入的类生成，该类实现了 Bmartel\Phperclip\Contracts\FileNameGenerator 接口。默认情况下，Phperclip 使用它自己的文件名生成器实现 Bmartel\Phperclip\FileNameGenerator。它已在配置中设置

	'filename_generator' => 'Bmartel\Phperclip\FileNameGenerator'

此实现将文件的选项和属性的 json 结果的 md5 哈希值作为文件名。如果您希望使用其他方式生成文件名，请创建自己的实现，并将类作为 Phperclip 的 config.php 文件中 filename_generator 的值包含进来。

存储

如果您打开在设置期间创建的 config.php 复制品，您会看到它已经填充了最典型设置配置选项。最基础的 Bmartel\Phperclip\Storage\Filesystem 驱动程序将简单地存储图像文件在您网站公开目录中。

Amazon S3 驱动程序

将 'config.php' 文件中的文件系统驱动程序配置替换为以下 Amazon AWS 配置。

[
	'storage' =>
	[
		'Bmartel\Phperclip\Storage\S3' =>
		[
			'aws_key' => 'YOUR_KEY_HERE',
			'aws_secret' => 'YOUR_SECRET_HERE',
            'aws_bucket' => 'phperclip-bucket'
		]
	]
]

处理器

Phperclip 并不规定您想要对文件做什么。相反，它通过 FileProcessors 插件提供对服务生命周期方法的钩子。FileProcessors 允许您指定它将负责的文件类型和生命周期方法：onBeforeSave、onSave、onDelete 和 onMove 允许您对文件执行任何您希望的处理。

以下生命周期方法在返回 false 类型时会中止当前操作。这些方法的正常运行条件是您返回传入的文件。

• onBeforeSave: 在任何文件被持久化之前执行。非常适合进行验证或其他预保存处理，在失败时您不希望创建文件。
• onSave: 在原始的、未修改的文件被持久化后立即执行。允许对文件进行修改。
• onDelete: 在文件即将被删除时执行。非常适合开始清理烦人的文件关系、执行验证或对请求文件删除的用户进行授权。
• onMove: 在文件将在槽位之间移动时执行。

提供了一个ImageProcessor，它既展示了FileProcessor组件的强大功能，也提供了灵活且可链式的图像过滤！

图像过滤器

Phperclip的过滤链是一个强大的功能，允许您在保存或检索图像时编排任意组合的修改。在处理链时，Phperclip对链中的每个过滤器执行以下操作

• 尝试实例化指定的类，该类必须实现Bmartel\Phperclip\Contracts\Filter
• 如果过滤器的配置是一个数组，则第二个索引中的每个键都将作为子类的setter方法被调用
• 在子类上调用run方法，传递原始图像和图像的数据库条目

您可能需要为项目预配置过滤链，这样在检索变体时就不需要重复它们。Phperclip使用简单的数组模式来定义过滤链。以下是一个示例

[

	'Bmartel\Phperclip\Processes\Image\FixRotation',
	
	[
		'Bmartel\Phperclip\Processes\Image\Resize',
		[
			'width' => 300,
			'height' => 300,
			'preserve_ratio' => true
		]
	],
	
	[
		'Bmartel\Phperclip\Processes\Image\Watermark',
		[
			'source_path' => sprintf('%s/logo.png', __DIR__),
			'anchor' => 'bottom-right'
		]
	]

]

• 数组不得使用键。
• 一个字符串条目将被实例化并运行，不带参数。
• 一个子数组条目将使用数组的第一个索引[0]实例化，第二个索引[1]转换为实例的setter
  • setWidth(300)
  • setHeight(300)
  • setPreserveRatio(true)
  • 等等...

如果您不确定应在何处存储您的过滤器配置文件，建议您将它们放置在您在之前发布Phperclip配置时创建的filters.php文件中。这将允许您根据环境调整过滤器配置，并将检索简化为Config::get('phperclip::filters.filter_name')

用法

根据您的实现方式，您接收文件的方式可能会有所不同。Phperclip不假设您的请求生命周期（或是否有请求！）并且仅关注接收Symfony\Component\HttpFoundation\File\File的实例。

Phperclip使用的两个可选的次要信息是Clippable，用于限制到特定的模型，以及一个选项数组，它允许对文件进行加工。

特质

如果您计划将文件附加到模型（用户、项目、图像库），则该模型必须实现接口Bmartel\Phperclip\Model\Clippable。这将强制您实现一个方法，您可以选择自行实现或方便地通过使用特质Bmartel\Phperclip\Model\ClippableImpl与Phperclip保持同步。

保存

文件保存是通过Phperclip服务完成的，该服务可以通过外观或通过依赖注入访问。

	/** @var \Symfony\Component\HttpFoundation\File\File $file */
	/** @var \Bmartel\Phperclip\Model\Clippable $clippable */

	$options = [
		'attributes' => ['slot' => 1]
	];

	/** @var \Bmartel\Phperclip\Model\File $file */
	$file = Phperclip::saveFromFile($file, $clippable, $options);

Phperclip在成功保存后将返回一个Bmartel\Phperclip\Model\File的实例。如果您提供了一个，则文件记录将与可剪切项关联。任何其他属性将通过选项数组的属性键传递到保存中。

检索

在检索单个文件时，您需要一种方法来识别它

• 文件的 id
• 文件的剪贴和槽位
• 文件的 clippedFiles() 关系

大多数情况下，您至少会有这三条信息之一，这将使您能够获得指向物理文件的 URI。

	Phperclip::getPublicUri($file, $options);
	Phperclip::getPublicUriBySlot($slot, $clippable, $options);
	Phperclip::getPublicUriById($id, $options);

您还可以通过剪贴、文件 MIME 类型或槽位检索文件集合。Phperclip 将返回 Bmartel\Phperclip\Model\File 的文件集合。

  Phperclip::getFilesFor($clippable, $mimetypes, $slot);

在从 Phperclip 检索文件时，记住“剪贴”是可选的，省略它或提供 null 表示 “全局”。同样，“选项”也是可选的，省略此值、提供 null 或空数组表示 “原始文件”。

槽位

Phperclip 具有一个称为槽位的概念，其核心仅仅是一个字符串值。槽位用于通过剪贴对文件进行排序和/或键控。在 Bmartel\Phperclip\Model\File 类上有帮助作用域，有助于根据槽位值检索文件。

Note: When storing files without a clippable (globally), keep in mind that they are all sharing the same slot scope and cannot have duplicates.

槽位的示例用例可以是“Item”类，它可以有一个相册以及一个“主要”图像。属于相册的图像将具有数字槽位，以便保持特定的顺序，而主要图像则位于可以直接查询的命名槽位中。

批次

实现通常需要一种方法，在单次传递中向剪贴的文件提交多个更改。这些更改有时可能存在冲突，并且难以解决。

作为便利，Phperclip 提供了一个服务批处理方法，允许执行这些批量操作。操作通过剪贴进行范围限制，并按安全顺序逐槽执行。

模式的结构与调用者无关，在不可避免地发生冲突的情况下，将取消任何被替换文件的槽位。

以下是执行批量操作时使用的模式示例

	$operations = [
		1 => 2,
		3 => 'thumbnail',
		4 => null,
		5 => 'http://placehold.it/200x200&text=Phperclip'
	];

	/** @var \Symfony\Component\HttpFoundation\File\File[] $newFiles */
	/** @var \Bmartel\Phperclip\Model\Clippable $clippable */

	Phperclip::batch($operations, $newFiles, $clippable);

在此示例中，以下操作将按顺序进行

• 槽位 1 和 2 的文件将被交换
• 槽位 3 的文件将被移动到“缩略图”槽位
• 槽位 4 的文件将被删除
• 位于 URI 的文件将被下载并插入到槽位 5

文件数组 $newFiles 将根据槽位键入，理论上可能包含槽位 4 的新文件。

当文件被指示移动到新的槽位时，如果目标槽位中已经有一个文件，则它们将被交换。如果上传的文件尝试进入已占用的槽位，则该槽位中现有的文件将被其槽位 null 化。

需要注意的是，在此模式中槽位键不能重复，因此最好提交尽可能简单的批处理列表。

驱动程序

创建驱动程序就像扩展类 Bmartel\Phperclip\Storage\Base 一样简单。您还可以使用 Bmartel\Phperclip\Storage\Filesystem 作为参考。

处理器

为了使文件发生魔法般的效果，您将想要实现一个专用的 FileProcessor 来处理文件服务生命周期中可能需要执行的任务。您指定类中处理器将执行的文件 MIME 类型，并根据自己的需求在生命周期方法中提供处理。

首先，实现接口 Bmartel\Phperclip\Contracts\FileProcessor。为了使用一些免费功能，例如内置文件验证和闪存消息，可以扩展类 Bmartel\Phperclip\Processes\FileProcessorAdapter。

图像过滤器实际上是通过包含的文件处理器 Bmartel\Phperclip\Processes\ImageProcessor 处理的！在创建自己的文件处理器时，可以将其作为参考。

图像过滤器

在您的项目或包中创建自己的图像过滤器非常简单。只需实现接口 Bmartel\Phperclip\Contracts\Filter 即可。

唯一的规则是，过滤器子类必须在不移动、重命名或删除文件的情况下对其提供的文件进行操作 - 覆盖是可以的。《run》方法不期望返回任何值。

在创建自己的图像过滤器时，请参考 Bmartel\Phperclip\Processes\Image\Resize 和 Bmartel\Phperclip\Processes\Image\FixRotation。

问题

如果您遇到任何问题、发现错误或有任何疑问，请随时在问题跟踪器中提交工单。

致谢

Brandon Martel - 维护者

Alex Trauzzi - 创建了 tippingcanoe/imager 的原始实现，本包基于该实现。