README

这是一个 twig 扩展，用于在 twig 模板中使用rokka相关方法。

此扩展提供筛选器和函数，将rokka散列或图像文件引用转换为rokka URL。一些筛选器在rokka URL上操作以添加堆栈选项。

当与文件引用一起工作时，此扩展可以根据需要将图像文件上传到rokka。动态上传引入了相当大的开销。如果您构建了一个CMS，我们建议在创建或后台过程中将图像上传到rokka，并在模板中使用rokka_image_hash与rokka_generate_url twig函数，以避免首次渲染的性能损失。动态上传的主要用例是静态网站生成器，您在其中预先渲染页面，然后部署已渲染的代码。

安装

注意：如果您使用Rokka Symfony Bundle，则twig扩展会自动安装并注册。

composer require rokka/twig`

将以下代码添加到您的 Twig\Environment 设置中

$twig->addExtension(new \Rokka\Twig\Extension\RokkaExtension('your_rokka_organistaion', 'your_api_key'));

通过这两个步骤，rokka筛选器和函数变得可用。

使用方法

您指定一个本地上可用的图像文件（或通过图像定位器，见下文）。twig扩展会检查它是否知道该图像的rokka散列，如果不知道，则将图像上传到rokka并存储散列。然后它使用rokka散列生成请求的URL。

存储和读取散列

默认情况下，插件会在每个图像文件旁边存储一个json文件。如果您想覆盖此行为（例如，将散列存储在数据库中），则需要扩展 \Rokka\Client\TemplateHelper\AbstractCallbacks 以实现所需的行为，并将该类的实例提供给 RokkaExtension 构造函数。

非标准图像文件位置

您可以编写自己的类来加载源图像，例如当它们不在本地文件系统时。实现 Rokka\Twig\Resolver\ResolverInterface 以实现您的图像加载逻辑，并将该类的实例提供给 RokkaExtension 构造函数。

Twig筛选器

筛选器应用于图像路径、SplFileInfo对象、rokka散列或 Rokka\Client\LocalImage\AbstractLocalImage 实例。

筛选器需要您要使用的 堆栈。在使用之前，请确保您已在rokka中定义了堆栈。

您可以强制一个 格式 以使rokka将您的图像转换为所需的格式。

大多数筛选器接受一个seo字符串和seo语言。语言用于将seo字符串转写为URL安全字符串（例如，对于德语，将ä转换为ae；对于法语，将é转换为e）。

rokka_stack_url: 使用所需的堆栈为rokka创建图像URL

rokka_stack_url(stack, format = "jpg", seo = null, seoLanguage = "de")

示例

{{ '/path/to/image' | rokka_stack_url('preview', seo='my-seo-image-url-fragment', seoLanguage = 'fr') }}

示例输出: https://my-org.rokka.io/preview/123abcde/my-seo-image-url-fragment.jpg

rokka_original_size_url: 创建输出原始大小的rokka图像URL

rokka_original_size_url(format = "jpg", seo = null, seoLanguage = "de")

图像将保持其原始大小，但经过优化、压缩并通过rokka的CDN交付。

rokka_resize_url: 使用动态堆栈创建rokka图像URL以缩放图像

rokka_resize_url(width, height = null, format = "jpg", seo = null, seoLanguage = "de")

动态堆栈将确保图像的宽度不超过width，高度不超过height。

rokka_resizecrop_url: 为rokka创建一个动态堆栈以调整和裁剪图像的图像URL

rokka_resizecrop_url(width, height, format = "jpg", seo = null, seoLanguage = "de")

类似于调整大小，但确保图像始终具有指定的宽度和高度。如果图像的纵横比不匹配，则裁剪较长的一边以适应尺寸。

rokka_add_options: 将rokka URL转换为添加选项

rokka_add_options(options)

这允许您动态配置堆栈并设置堆栈选项和变量。

示例

{{ '/path/to/image' | rokka_stack_url('preview') | rokka_add_options('options-jpg.quality-80') }}
{{ '/path/to/image' | rokka_stack_url('preview') | rokka_add_options('resize-width-200') }}
{{ '/path/to/image' | rokka_stack_url('preview') | rokka_add_options('resize-width-200--options-jpg.quality-80') }}

rokka_src_attributes: 将rokka URL转换为CSS片段以用于retina图像的CSS

rokka_src_attributes(multipliers = [2])

示例

{{ '/path/to/image' | rokka_stack_url('large') | rokka_src_attributes }}

输出示例：background-image:url('https://liip.rokka.io/stack/imagehash.jpg'); background-image: -webkit-image-set(url('https://liip.rokka.io/stack/imagehash.jpg') 1x, url('https://liip.rokka.io/stack/options-dpr-2/imagehash.jpg') 2x);

rokka_background_image_style: 将rokka URL转换为HTML图像标签片段以用于retina

rokka_background_image_style(multipliers = [2])

示例

{{ '/path/to/image' | rokka_stack_url('large') | rokka_background_image_style }}

输出示例：src="https://org.rokka.org/stack/imagehash.jpg" srcset="https://org.rokka.org/stack/options-dpr-2/imagehash.jpg"

Twig函数

rokka_generate_url(hash, stack, format = "jpg", seo = null, seoLanguage = "de")

输出：为指定的图像哈希和堆栈生成的rokka URL，如果指定，包含"seo"-文件名。

开发

运行PHP-CS-Fixer

composer cs:fix

运行phpstan

composer phpstan