avor kracht10/php-uploadcare-transformations

使用Uploadcare生成图像变换和处理的URL的Composer包。

维护者

详细信息

github.com/vormkracht10/php-uploadcare-transformations

主页

源代码

问题

资助包维护！
avor kracht10

安装次数: 8,128

依赖关系: 0

建议者: 0

安全性: 0

星星: 13

关注者: 2

分支: 0

开放问题: 0

v1.0.7 2024-07-09 12:50 UTC

Requires

  • php: ^8.1

Requires (Dev)

MIT a736bbf35871774b035e2d510f39589634756ae0

  • Bas van Dinther <bas.woop@vormkracht10.nl>

vormkracht10php-uploadcare-transformations

This package is auto-updated.

Last update: 2024-09-09 13:11:57 UTC

README

Total Downloads Tests PHPStan GitHub release (latest by date) Packagist PHP Version Support Latest Version on Packagist

生成Uploadcare图像处理URL，用于变换和处理您的图像。无需自己编写或生成URL。只需传递文件的UUID，可选地传递自定义CDN，并将您想要应用的方法链式传递给UploadcareTransformation类，该包会为您生成URL。

要求

  • PHP 8.1+

安装

您可以通过composer安装此包

composer require vormkracht10/php-uploadcare-transformations

用法

  1. 导入UploadcareTransformation。
  2. 获取您想要显示的文件的UUID。
  3. 设置您的CDN URL（可选）。
  4. 通过将一个或多个方法链式传递给UploadcareTransformation类来创建变换URL。您可以链式传递任意多的方法。
  5. 使用变换的输出作为图像源。
use Vormkracht10\UploadcareTransformations\UploadcareTransformation;

$uuid = '12a3456b-c789-1234-1de2-3cfa83096e25';
$cdnUrl = 'https://example.com/cdn/';

$transformation = (new UploadcareTransformation($uuid, $cdnUrl));

$url = $transformation->crop(width: 320, height: '50p', offsetX: 'center')->setFill(color: 'ffffff');

echo $url;
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/-/crop/320x50p/center/-/set_fill/ffffff

如果您更喜欢使用简短版本，您也可以使用辅助方法

$uuid = '12a3456b-c789-1234-1de2-3cfa83096e25';
$cdnUrl = 'https://example.com/cdn/';

$url = uc($uuid, $cdnUrl)
        ->crop(width: 320, height: '50p', offsetX: 'center')
        ->setFill(color: 'ffffff')
        ->getUrl();

echo $url;
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/-/crop/320x50p/center/-/set_fill/ffffff

使用Laravel框架

当您使用Laravel框架时，您可能最好在您的.env文件中定义CDN，并在配置文件中获取该值。您可以创建一个专门的config/uploadcare配置或将其添加到config/services文件中。

您的.env文件

UPLOADCARE_CDN_URL=https://ucarecdn.com
UPLOADCARE_PROXY_URL=https://endpoint.ucr.io

添加到config/services.php文件

'uploadcare' => [
    'cdn_url' => env('UPLOADCARE_CDN_URL', 'https://ucarecdn.com'),
    'proxy_url' => env('UPLOADCARE_PROXY_URL', 'https://endpoint.ucr.io'),
],

在您的代码中

$url = uc($uuid, config('services.uploadcare.cdn_url'))->crop(width: 320, height: '50p', offsetX: 'center')->setFill(color: 'ffffff');

文档

使用百分比或像素作为参数

在有些方法中，您可以通过多种方式传递参数。例如，在scaleCrop()方法中，您可以以百分比或像素的形式传递偏移量。为了更容易识别像素或百分比的使用，您可以按照以下方式传递参数。

// Using percentages
$url = $transformation->scaleCrop(width: 320, height: 320, offsetX: '50p', offsetY: '60p');
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/scale_crop/320x320/50px60p/


// Using pixels
$url = $transformation->scaleCrop(width: 320, height: 320, offsetX: 50, offsetY: 60);
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/scale_crop/320x320/50x60/

如Uploadcare文档所述，在URL中，%是转义字符，应该使用%25转义序列进行编码，例如 /scale_crop/440x440/80%25,80%25/。为了方便，我们可以使用p快捷方式表示百分比，无需编码。

可能的变换列表

每个变换都遵循Uploadcare文档，您可以在这里找到。可能的变换列表和文档位置

用法

添加文件名

原始文件名可以通过Uploadcare的REST API访问。这可以通过发送一个请求来接收一个包含文件参数的JSON响应来实现，包括original_filename。

您可以为用户看到的文件名设置一个可选的文件名，而不是原始名称

$url = $transformation->autoRotate(false)->filename('my-filename.jpg');
// https://example.com/cdn/.../-/autorotate/no/my-filename.jpg

请注意，文件名应符合文件名约定。有关如何使用文件名的更多信息，请参阅Uploadcare API文档。

自动旋转

默认行为是对原始图像的EXIF标签进行解析，并根据“方向”标签旋转图像。使用false作为参数可以关闭默认行为。

$url = $transformation->autoRotate(false);
// https://example.com/cdn/.../-/autorotate/no/

$url = $transformation->autoRotate(true);
// https://example.com/cdn/.../-/autorotate/yes/

基本颜色调整

值参数控制任何应用的调整的强度。值参数的范围因操作而异。每个操作还有一个零点——产生与原始图像相同输出的值。

调整（颜色）必须是以下值之一：brightness、exposure、contrast、saturation、gamma、vibrance、warmth。

要查看基于所选调整的允许值的完整概述，请参阅Uploadcare文档。

$url = $transformation->basicColorAdjustments(color: 'brightness', value: 50);
// https://example.com/cdn/.../-/adjust/brightness/50/

模糊

通过强度因子模糊图像。过滤模式是高斯模糊，其中强度参数设置模糊半径——效果强度。

$url = $transformation->blur(strength: 50, amount: null);
// https://example.com/cdn/.../-/blur/50/

模糊人脸

当指定面孔时，通过利用面部检测自动选择区域。

$url = $transformation->blurFaces(strength: 50);
// https://example.com/cdn/.../-/blur_faces/50/

模糊区域

通过强度因子模糊图像的指定区域。过滤模式是高斯模糊，其中强度参数设置模糊半径——效果强度。

尺寸和坐标必须是像素或百分比。

// Using pixels.
$url = $transformation->blurRegion(dimensionX: 250, dimensionY: 250, coordinateX: 50, coordinateY: 50, strength: 200);
// https://example.com/cdn/.../-/blur_region/250/250/50/50/200/

// Using percentages.
$url = $transformation->blurRegion(dimensionX: '50p', dimensionY: '50p', coordinateX: '80p', coordinateY: '20p', strength: 200);
// https://example.com/cdn/.../-/blur_region/50p/50p/80p,20p/200/

转换为sRGB

操作设置Uploadcare根据上传图像的不同颜色配置文件的行为。有关可能的输出的更多信息，请参阅Uploadcare文档。

配置文件参数必须是以下值之一：fast、icc、keep_profile。

$url = $transformation->convertToSRGB(profile: 'icc');
// https://example.com/cdn/.../-/srgb/icc/

裁剪

使用指定的尺寸和定位裁剪图像。

尺寸参数可以是像素或百分比。要了解如何使用像素或百分比，请参阅使用百分比或像素作为参数段落。

定位也可以是像素和百分比，但也可以使用快捷方式。可能的值是：top、center、bottom、left、right。

// Using percentages and a shortcut.
$url = $transformation->crop(width: 100, height: '50p', offsetX: 'center');
// https://example.com/cdn/.../-/crop/100x50p/center/

// Using pixels only.
$url = $transformation->crop(width: 100, height: 100, offsetX: 50, offsetY: 50);
// https://example.com/cdn/.../-/crop/100x100/50,50/

// Using both pixels and percentages.
$url = $transformation->crop(width: 100, height: '50p', offsetX: '25p', offsetY: '25p');
// https://example.com/cdn/.../-/crop/100x50p/25p,25p/

按对象裁剪

将图像裁剪到由标签参数指定的对象。

标签可以是face或image。

比率是两个大于零的数，由冒号分隔。比率是这些数的除法商。

尺寸和定位必须设置为百分比。在定位的情况下，您还可以使用快捷方式。可能的值是：top、center、bottom、left、right。如果没有指定定位，则使用center值。

当与标签一起使用时，尺寸应该是相对的。因此，您需要用像素设置宽度和高度。

// Using no ratio, percentages and pixels combined.
$url = $transformation->cropByObjects(tag: 'face', ratio: null, width: '50p', height: '50p');
// https://example.com/cdn/../-/crop/face/50px50p/

// Using ratio, percentages and a shortcut.
$url = $transformation->cropByObjects(tag: 'face', ratio: '4:3', width: '50p', height: '50p', offsetX: 'bottom');
// https://example.com/cdn/../-/crop/face/4:3/50px50p/bottom/

按比例裁剪

将图像裁剪到指定的宽高比，裁剪掉图像的其余部分。

比率是两个大于零的数，由冒号分隔。比率是这些数的除法商。

定位可以是像素和百分比，也可以使用快捷方式。可能的值是：top、center、bottom、left、right。如果没有指定定位，则使用center值。

// Using percentages and a shortcut.
$url = $transformation->cropByRatio(ratio: '4:3', offsetX: 'bottom');
// https://example.com/cdn/.../-/crop/4:3/bottom/

// Using percentage in combination with pixels.
$url = $transformation->cropByRatio(ratio: '4:3', offsetX: '50p', offsetY: 240);
// https://example.com/cdn/.../-/crop/4:3/50p,240/

增强

通过执行以下操作自动增强图像：自动级别、自动对比度和饱和度锐化。

强度必须是一个介于0和100之间的数字。默认值是50。

$url = $transformation->enhance(strength: 50);
// https://example.com/cdn/.../-/enhance/50/

滤镜

通过名称应用预定义的相片滤镜。您的图像外观会影响它们的参与率。您通过应用滤镜提供美丽的图像，这些图像在您发布的内容元素中保持一致。

名称参数可以是以下之一：adaris、briaril、calarel、carris、cynarel、cyren、elmet、elonni、enzana、erydark、fenralan、ferand、galen、gavin、gethriel、iorill、iothari、iselva、jadis、lavra、misiara、namala、nerion、nethari、pamaya、sarnar、sedis、sewen、sorahel、sorlen、tarian、thellassan、varriel、varven、vevera、virkas、yedis、yllara、zatvel、zevcen。

数量参数必须是一个在 -100 到 200 之间的数字。

$url = $transformation->filter(name: 'adaris', value: 50);
// https://example.com/cdn/.../-/filter/adaris/50/

翻转

翻转图像。

$url = $transformation->flip();
// https://example.com/cdn/.../-/flip/

格式

将图像转换为以下格式之一：jpg、png、webp、auto。

$url = $transformation->format(format: 'jpeg');
// https://example.com/cdn/.../-/format/jpg/

灰度

去除图像的饱和度。该操作没有其他参数，并且当应用时简单地产生一个灰度图像输出。

$url = $transformation->grayscale();
// https://example.com/cdn/.../-/grayscale/

ICC配置文件大小阈值

该操作定义了在 fast 或 icc 模式下使用 srgb 时，哪些 RGB 颜色配置文件大小将被视为“小”和“大”。number 代表 ICC 配置文件大小（单位：千字节）。

默认值为 10（10240 字节）。大多数常见的 RGB 配置文件大小（sRGB、Display P3、ProPhoto、Adobe RGB、Apple RGB）都在阈值以下。

请注意，因为这个转换应该始终与 convertToSRGB() 结合使用，所以它的方法应该在 convertToSRGB() 之后调用。否则，ICC 配置文件大小阈值会被 convertToSRGB() 转换覆盖。

$url = $transformation->convertToSRGB(profile: 'fast')->iccProfileSizeThreshold(number: 10);
// https://example.com/cdn/.../-/max_icc_size/10/srgb/fast/

反转

反转图像，生成输入的“负片”。

$url = $transformation->invert();
// https://example.com/cdn/.../-/invert/

镜像

镜像图像。

$url = $transformation->mirror();
// https://example.com/cdn/.../-/mirror/

叠加

覆盖操作允许将图像层层叠加。这里最常见的用例之一是水印：将半透明图像叠加在不透明图像上，以使它们的未经授权的使用复杂化等。

每个覆盖参数都是可选的，可以省略。但是，应该保留参数 URL 指令的顺序。例如，如果您想使用 coordinateX 参数，您还应该指定 width 和 height 参数。此外，请注意，opacity 参数应以百分比指定。

$uuidOverlay = 'e6b0c1c0-1b1a-4b1a-9b1a-1b1a1b1a1b1a';

$url = $transformation->overlay(
  uuid: $uuidOverlay,
  width: 150,
  height: 150,
  coordinateX: 200,
  coordinateY: 300,
  opacity: '25p'
)->getUrl();
// https://example.com/cdn/.../-/overlay/e6b0c1c0-1b1a-4b1a-9b1a-1b1a1b1a1b1a/150x150/200,300/25p/

预览

按比例调整图像大小，使其适应给定的像素宽度和高度。

$url = $transformation->preview(width: 100, height: 100);
// https://example.com/cdn/.../-/preview/100x100/

渐进式

返回一个渐进式图像。在渐进式图像中，数据在多个逐步提高细节的压缩过程中压缩。该操作不影响非 JPEG 图像；不会强制图像格式为 JPEG。

$url = $transformation->progressive(true);
// https://example.com/cdn/.../-/progressive/yes/

$url = $transformation->progressive(false);
// https://example.com/cdn/.../-/progressive/no/

质量

设置输出 JPEG 和 WebP 的质量。由于实际设置因编解码器而异，更重要的是，因格式而异，我们提供了五个简单的级别和两个自动值，这些值适用于大多数图像分发情况，并且是一致的。

质量必须是以下值之一：smart、smart_retina、normal、better、best、lighter、lightest。

$url = $transformation->quality(quality: 'smart');
// https://example.com/cdn/.../-/quality/smart/

光栅化

光栅化 SVG 图像。

$url = $transformation->rasterize();
// https://example.com/cdn/.../-/rasterize/

调整大小

将图像调整到一维或二维。当您明确设置宽度和高度时，可能会导致图像扭曲。如果您指定任意一边，此操作将保留原始纵横比并相应地调整图像大小。模式应该是以下值之一：on、off、fill。

// Using width, height, stretch and 'fill' mode.
$url = $transformation->resize(width: 100, height: null, stretch: true, mode: 'fill');
// https://example.com/cdn/.../-/resize/100x/stretch/fill/

// Using only height, no stretch and no mode.
$url = $transformations->resize(width: null, height: 250, stretch: false);
// https://example.com/cdn/.../-/resize/250x/

旋转

逆时针进行直角图像旋转。角度值必须是 90 的倍数。

$url = $transformation->rotate(angle: 180);
// https://example.com/cdn/.../-/rotate/180/

比例裁剪

缩放图像，直到它完全覆盖指定的尺寸；其余部分将被裁剪。主要用于将各种尺寸的图像放入占位符（例如，方形）中。

尺寸必须以像素为单位设置。

对齐必须以百分比或快捷方式设置。可能的值是：top、center、bottom、left、right。如果没有指定对齐，则使用 0,0 值。

// Using percentages.
$url = $transformation->scaleCrop(width: 100, height: 100, offsetX: '30p', offsetY: '50p');
// https://example.com/cdn/.../-/scale_crop/100x100/30p,50p/

// Using shortcut.
$url = $transformation->scaleCrop(width: 100, height: 100, offsetX: 'bottom');
// https://example.com/cdn/../-/scale_crop/100x100/bottom/

设置填充

设置与裁剪、拉伸或将启用 alpha 通道的图像转换为 JPEG 时使用的填充颜色。

颜色必须是不带井号的十六进制颜色代码。

$url = $transformation->setFill(color: 'ff0000');
// https://example.com/cdn/.../-/setfill/ff0000/

锐化

增强图像清晰度，特别适用于经过缩放处理的图像。强度范围在0到20之间，默认值为5。

$url = $transformation->sharpen(strength: 20);
// https://example.com/cdn/.../-/sharp/20/

智能裁剪

将裁剪类型切换到智能模式之一，将启用内容感知机制。Uploadcare应用基于AI的算法来检测人脸和其他视觉敏感对象，裁剪背景而不是主要对象。

尺寸必须以像素为单位设置。

类型必须是以下值之一：smart、smart_faces_objects、smart_faces、smart_objects、smart_faces_points、smart_points、smart_objects_faces_points、smart_objects_points或smart_objects_faces。

对齐必须设置为百分比或快捷方式。可能的值有：top、center、bottom、left、right。如果未指定对齐，则使用0,0值。

// Using percentages.
$url = $transformation->smartCrop(width: 100, height: 100, type: 'smart_faces_objects', offsetX: '30p', offsetY: '50p');
// https://example.com/cdn/.../-/scale_crop/100x100/smart_faces_objects/30p,50p/

// Using shortcut.
$url = $transformation->smartCrop(width: 100, height: 100, type: 'smart_faces_objects', offsetX: 'right');
// https://example.com/cdn/.../-/scale_crop/100x100/smart_faces_objects/right/

智能调整大小

内容感知调整大小有助于在调整图像其余部分的大小时，使用智能算法保留人脸和其他视觉敏感对象的原始比例。

$url = $transformation->smartResize(width: 500, height: 500);
// https://example.com/cdn/.../-/smart_resize/500x500/

缩放对象

缩放对象操作最适合具有均匀或统一背景的图像。

缩放必须是介于1到100之间的数字。

$url = $transformation->zoomObjects(zoom: 50);
// https://example.com/cdn/.../-/zoom_objects/50/

测试

./-/vendor/bin/pest

变更日志

有关最近更改的详细信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞，请参阅我们的安全策略。

鸣谢

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可文件。