README

BRJ 组织

图像生成器

轻松动态生成数千种图像类型，
设置数十个配置参数并自定义输出，
成熟工具，在 Latte 模板和后端中舒适地工作。

图像生成器是使用URL中特定参数进行调用，在前端简单处理图像的方式。为了避免生成器被轻易过载，所有图像都会进行校验和处理。

基本理念

在ImageGenerator引入之前，管理图像及其尺寸是一个非常复杂的工作，需要大量复杂的代码。

ImageGenerator引入了一种简单的方法，可以基于源图像和配置参数即时创建新图像并缓存它。只有应用程序可以发送请求来生成新的图像变体（由校验和处理）。如果请求的变体不存在，它将被自动生成。

这种方法可以轻松创建数千个图像变体，并轻松地从一种尺寸切换到另一种尺寸。原始源图像永远不会改变，是只读的。

📦 安装

最好使用 Composer 进行安装，您也可以在 Packagist 和 GitHub 上找到此包。

要安装，只需使用以下命令

$ composer require baraja-core/image-generator

您可以通过创建内部类的实例手动使用该包，或者注册DIC扩展将服务直接链接到Nette框架。

通过Linux库扩展

要使用高级功能，您需要在服务器上安装以下Linux库（可选）

在模板中使用生成器

ImageGenerator包含Latte模板系统的原生适配器。

{imageGenerator '/animal/cat.png', ['w' => 200]}

以常规方式将参数数组传递给 imageGenerator 宏。此外，还可以传递 alt 参数，它携带有关替代图像描述的信息。

或者，我们也可以通过 n:src 参数添加图像路径，并自行确定整个渲染逻辑

<img n:src="/animal/cat.png, [w => 200]">

请求（内部/外部）图像变体URL

您可以通过调用 ImageGenerator::from() 方法请求渲染图像，传递磁盘路径（相对、绝对或URL）和图像编辑参数。

URL也可以指向外部域。在这种情况下，图像将由机器人自动下载。下载的图像的副本将缓存在本地磁盘上，并按常规方式处理。为了将外部图像渲染到您的域，结果图像必须通过默认URI image-generator-proxy/* 下的内部PHP代理返回。

例如

$newUrl = ImageGenerator::from($url, ['w' => 100, 'h' => 380]);

如何处理图像请求

所有通过ImageGenerator接收到的图像都具有此格式

	<basePath>/<dir>/<fileName>__<parameters>_<hash>.<format>

当第一次调用图像时，将运行一个专门的PHP脚本来根据设置的参数准备和缓存图像。下一次调用图像时，它已经缓存，并且可以直接从那里调用，而不需要PHP脚本的辅助。

缓存

缓存位于 /www/_cache 目录中，并且包含与所有其他加载图片的源目录相同的目录结构。此结构在图像生成过程中自动维护。

如果需要生成与现有图像内容相同的图像，它将被自动追踪并创建符号链接，以节省磁盘空间。

缓存失效

在正常情况下，缓存永远不会失效，并将维护所有图像的完整历史记录。如果您想使缓存失效，只需调用 Helper::invalidateCache() 函数。

第一个参数传递原始图像的路径（从 /www 相对）
然后是 /www 目录的绝对路径（如果为 NULL，将自动检测），
最后一个参数（一个布尔值）可以用来指定是否应该递归地在子目录中使图像失效。

参数

在调用图像文件时，可以直接使用 URL 中的参数来影响生成器的行为。所有参数都写在两个下划线之后，并且没有参数是强制的（所有都有默认值）。如果没有传递任何参数，则直接从源位置返回原始图像，而不进行任何更改。

在传递给生成器之前，参数会自动验证。无效输入会被忽略（跳过），并使用其他可用的参数生成新图像。

调用图像的示例

	<basePath>/<dir>/monalisa__w200h128_ABCDEF.jpg

此路径从路径 /dir/monalisa.jpg 读取图像，并设置以下过滤器

宽度：200px
高度：128px
居中方法（裁剪）：'smart'（使用默认过滤器）
缩放（纵横比）：无（不需要，图像不会被扭曲）
哈希：'ABCDEF'（将验证哈希参数）

然后调用源图像，应用过滤器，并将结果缓存。

所有参数列表

我们区分以下参数

高度和宽度（宽 & 高）

参数对 'w' 和 'h' 通常紧随其后。如果其中一个未指定，它将根据纵横比计算。

参数后面直接跟一个像素维度的整数。

示例符号：w200h128

按边缘裁剪（裁剪）

'c' 参数告诉从 'w' 和 'h' 参数裁剪到设置大小的位置。它不会执行任何其他优化（纵横比等），它只是大致裁剪到设置的大小。

它有9种可能的状态，取决于位置

TL TC TR
ML MC MR
BL BC BR

还有一个特殊状态：sm，表示 'smart-crop'，即“我不知道在哪里裁剪图像，自己做出智能决策”。

示例符号：-ctl 表示从左上角裁剪图像。

提示：如果您需要根据不同的分辨率以相同规则裁剪一组图像，最好使用断点（详情见下一章）。

处理不同边长的方法（缩放）

有时更改不同页面长度下的变形和裁剪行为很有用——您可能需要填充指定空间，或者相反，放大。

此状态有3种可能

'r' - 比例（将保持纵横比，较大的边给出主要维度），
'c' - 覆盖（尽量在指定矩形内根据纵横比填充尽可能多的区域），
'a' - 绝对（无论纵横比如何，都将压缩/拉伸图像到确切的尺寸，可能会造成变形）。

示例符号：-scr 表示 'scale ratio'（缩放比例）

断点

由于AirBank网站上图片较大，我们实现了设置自定义断点的功能，通过该功能对图片进行裁剪。当使用-br参数时，其他所有参数都会被忽略，所使用的断点由所需图片的宽度（w参数）决定。

断点在neon配置文件中定义，无法更改参数。

断点的使用是一种根据非结构化规则控制图片裁剪的方式。如果需要不在断点中列出的尺寸，则使用下一个更大的尺寸。

默认设置

Breakpoint: [upper left corner, lower right corner]
480: [910, 30, 1845, 1150]
600: [875, 95, 1710, 910]
768: [975, 130, 1743, 660]
1024: [805, 110, 1829, 850]
1280: [615, 63, 1895, 800]
1440: [535, 63, 1975, 800]
1680: [410, 63, 2090, 800]
1920: [320, 63, 2240, 800]
2560: [0, 63, 2560, 800]

按百分比确定的等比例裁剪

通常情况下（尤其是在响应式网站上），直接裁剪到特定边缘并不是一个好主意，而是基于源图片的宽高比作为百分比进行裁剪。对于这些我们不知道原始尺寸的图片，我们不知道最佳的裁剪区域。这正是按比例百分比裁剪解决的问题。

首先分析确切的宽高比以确定要裁剪的参数（另一个将被忽略），然后根据指定的百分比计算裁剪区域，并进行裁剪。

注意：这两个值不用于裁剪，但总是根据当前宽高比自动确定更好的值！

如果您想使用此参数，则必须指定两个必需的值

'px' - 根据X轴的百分比裁剪
'py' - 根据Y轴的百分比裁剪

示例条目：-px52-py70表示图片裁剪将从顶部边缘向上移动52%，从左侧边缘向右移动70%。对应于源宽高比的那一侧边缘将始终使用，另一维度将在整个剩余的图片区域内拉伸。

在px和py之后给出的值是0到100的整数百分比。不允许使用负值。

参数组合

参数可以（几乎）任意组合。不相关的单个参数由连字符分隔。

调用图片的示例：/data/cms/main-page__w1680h800-px75-py0_7fd364.jpg

将调用图片main-page.jpg，裁剪到1680x800的尺寸，从顶部裁剪75%，从左侧裁剪0%。

格式转换

我们经常在磁盘上有一些图片，例如png格式，这对于数据传输来说不经济，而jpg格式就足够了。如果没有与相同名称的.jpg扩展名的图片，可以在调用图片时更改扩展名（并调用不存在的图片），并让生成器自动追踪源文件并转换格式。

例如，如果有一个cat.png文件，我们对其jpg版本感兴趣，我们只需调用cat.jpg，格式就会转换（它不影响源图片，转换后的文件将缓存）。

数据优化

许多图片（尤其是大照片）具有不必要过大的容量，这会减慢网络传输速度。图片生成器自动对所有输出图片应用数据优化。目前，它将质量转换为85%。此值直接在生成器中手动设置，不能通过任何参数来影响。

📄 许可证

baraja-core/image-generator在MIT许可证下授权。有关更多详细信息，请参阅LICENSE文件。

baraja-core / image-generator

维护者

详细信息