README

这个 PHP 库是官方 Sanity JavaScript 库 @sanity/image-url 的直接移植。版本对应 @sanity/image-url @fff9fc1，发布日期为 2024 年 8 月 8 日。

快速从 Sanity 图像记录生成图像 URL。

默认情况下，该助手将尊重提供给它的任何在 Sanity 内容中指定的裁剪/热点。最典型的用例是将一个 Sanity 图像和一个宽度、高度或两者都指定给它，以获得一个根据内容编辑器的意愿和前端开发人员的规格裁剪和调整大小的良好图像。

除了核心用例之外，这个库还提供了一个方便的构建器，可以访问 Sanity 图像管道中可用的丰富处理选项。

要求

sanity-image-url-php 需要 PHP >= 7.4。

Composer

您可以通过 Composer 安装该库。运行以下命令

composer require robertpainsi/sanity-image-url-php

要使用该库，请使用 Composer 的 自动加载

require_once 'vendor/autoload.php';

用法

在您的项目中使用此库最常见的方式是通过传递您的 sanity 客户端配置来配置它。这样，它将自动预配置到您当前的项目和数据集中

use function SanityImageUrl\urlBuilder;

$builder = urlBuilder( [
    'projectId' => 'zp7mbokg',
    'dataset'   => 'production',
    // ...
] );

function urlFor( $source ) {
    global $builder;

    return $builder->image( $source );
}

当与官方的 sanity-php 库一起工作时，您还可以通过传递 Sanity\Client 作为参数来初始化 urlBuilder。

$client  = new Sanity\Client( [
    'projectId' => 'zp7mbokg',
    'dataset'   => 'production',
    // ...
] );
$builder = urlBuilder( $client );

一旦初始化了构建器，您就可以使用方便的构建器语法来生成您的 URL

<img src="<?php echo urlFor( $author[ 'image' ] )->width( 200 )->url(); ?>" />

这将确保作者图像始终为 200 像素宽，自动应用编辑器指定的任何裁剪，并朝向她绘制的热点裁剪。您可以通过这种方式指定宽度和高度

<img src="<?php echo urlFor( $movie[ 'poster' ] )->width( 500 )->height( 300 )->url(); ?>" />

您可以指定大量有用的选项，例如例如模糊

<img src="<?php echo urlFor( $mysteryPerson[ 'mugshot' ] )->width( 200 )->height( 200 )->blur( 50 )->url(); ?>" />

请注意，需要将 url() 函数作为最后一个函数来输出 URL 字符串。

完整用法示例

// author.ts
export default {
    name: 'author',
    type: 'document',
    title: 'Author',
    fields: [{
        name: 'image',
        type: 'image',
        title: 'Image',
        options: {
            hotspot: true,
        }
    }]
}

// author.php
require_once 'vendor/autoload.php';

use function SanityImageUrl\urlBuilder;

const SANITY_CONFIG = [
    'projectId' => 'zp7mbokg',
    'dataset'   => 'production',
];

$client  = new Sanity\Client( SANITY_CONFIG );
$builder = urlBuilder( $client ); // Instead of $client you can also use the SANITY_CONFIG array

$authors = $client->fetch( "*[_type == 'author']" );
foreach ( $authors as $author ) {
    echo '<img src="' . $builder->image( $author[ 'image' ] )->width( 320 )->height( 640 )->url() . '" />';
}

构建器方法

image( $source )

指定要渲染的图像。接受 Sanity image 记录、asset 记录或仅字符串资产 ID。为了应用热点/裁剪处理，必须提供 image 记录以及宽度和高度。

dataset( $dataset )，projectId( $projectId )

通常您应该预先配置您的构建器以数据集和项目 ID，但在您这样做的情况下，这些选项允许您在需要渲染来自其他项目或数据集的资产时临时覆盖它们。

width( $pixels )

指定渲染图像的宽度（以像素为单位）。

height( $pixels )

指定渲染图像的高度（以像素为单位）。

size( $width, $height )

一次性指定宽度和高度。

focalPoint( $x, $y )

指定裁剪图像时关注的中心点。值为 0.0 到 1.0 的图像尺寸分数。当指定时，将覆盖图像记录中的任何裁剪或热点。

blur( $amount )，sharpen( $amount )，invert()

应用图像处理。

rect( $left, $top, $width, $height )

以像素为单位指定裁剪。覆盖图像记录中的任何裁剪/热点。

format( $name )

指定图像的格式。'jpg', 'pjpg', 'png', 'webp'

auto( $mode )

根据浏览器功能指定要自动应用的转换。支持的值

• format - 如果支持，自动使用 WebP

orientation( $angle )

旋转角度。可接受值：0，90，180，270

quality( $value )

如有适用，则指定压缩质量。0-100

forceDownload( $defaultFileName )

使此为下载图像的url。指定用户将被建议的文件名。

flipHorizontal()，flipVertical()

翻转图像。

crop( $mode )

指定如何裁剪图像。当指定时，覆盖图像记录中的任何裁剪或热点。有关详细信息，请参阅文档。

fit( $value )

配置fit模式。有关详细信息，请参阅文档。

dpr( $value )

指定设备像素比缩放因子。从1到3。

saturation( $value )

调整图像的饱和度。目前唯一支持的值是-100 - 表示将图像转换为灰度。

ignoreImageParams()

忽略图像记录中的任何指定（即裁剪和热点）。

url()，__toString()

以字符串形式返回url。

pad( $value )

指定填充图像的像素数。

frame( $value )

指定要转换的动画图像帧。可接受值

• 1 - 返回动画图像的第一帧作为图像的静态预览。

已弃用：minWidth( $pixels )，maxWidth( $pixels )，minHeight( $pixels )，maxHeight( $pixels )

裁剪时指定最小/最大尺寸。

已弃用：您通常希望使用width/height与max或min的fit模式一起使用。

自定义CDN域名

ℹ️ 此功能适用于选择企业账户。请联系您的销售经理了解更多信息。

您可以在构建器选项中指定自定义baseUrl以覆盖默认值（https://cdn.sanity.io）

$builder = urlBuilder( [
    'baseUrl'   => 'https://my.custom.domain',
    'projectId' => 'abc123',
    'dataset'   => 'production',
] );

echo $builder->image( 'image-928ac96d53b0c9049836c86ff25fd3c009039a16-200x200-png' )
    ->auto( 'format' )
    ->fit( 'max' )
    ->width( 720 )
    ->toString();

// output: https://my.custom.domain/images/abc123/production/928ac96d53b0c9049836c86ff25fd3c009039a16-200x200.png?w=720&fit=max&auto=format

功能请求

目前，没有计划支持不在官方JavaScript项目中的功能。请在新官方GitHub项目上请求新功能，如果被接受并实现，此库也将在以后某个时间点实现此功能。

问题

在提交新问题之前，请检查是否已存在。如果不存在，请验证此问题是否也存在于官方JavaScript项目中。如果JavaScript代码和PHP代码的行为不同，请随时报告问题。

拉取请求

只有针对官方JavaScript项目和此PHP项目之间行为差异的拉取请求将被考虑。PHP代码几乎逐行从JavaScript代码移植过来，这将使未来的更新更容易实现。对结构或可读性的更改可能会导致未来的更新速度较慢，应避免。因此，让我们尝试保持PHP代码和JavaScript代码同步 🤝

许可证

MIT © Robert Painsi