README

将Cloudinary的强大功能带到SilverStripe！

Cloudinary是一个基于云的媒体管理平台，为开发者提供了一种简单的方法来存储、管理和提供高度优化的即时数字资产。

关于分支、版本和PHP版本的一些说明

如果您正在使用低于PHP 8的任何版本，请使用legacy分支和6.x.x版本。

对于运行在PHP 8.1及以上版本的任何项目，应使用main分支和^7.x.x版本。

SilverStripe有资产管理系统，为什么还需要这个？
提供Cloudinary配置
创建数据库字段
设置表单字段
- 附加方法
内联编辑器
- 内联编辑器的附加设置
  - default_transformations选项
渲染资产
辅助方法
全局配置
多资源字段
保留变换
主色
贡献
待办事项
迁移
- 步骤1
- 步骤2
- 步骤3
- 步骤4

SilverStripe有资产管理系统，为什么还需要这个？

开箱即用的资产管理系统有一个致命的缺陷：资产存储在服务器上。你可能想“嗯，当然了，它们还能在哪里？”

对于不需要服务器和良好缓存的网站来说，将资产存储在服务器上是可行的。但是当你有一个多服务器配置，并且所有实例都需要提供相同的资产时，问题就出现了。

在多个服务器上保持资产同步确实是一个头疼的问题。是的，它可以自动化，但需要有人去做，这意味着必须有一个开发员将流程放在合适的位置，还需要有一个码农在旁边以防万一出点意外。真头疼。

最简单的解决方案是将资产移至云端。那个声音又出现了：“已经有了做这个的S3模块。”

是的，确实有。但你需要去实施它。然后你需要设置S3，可能还需要在某个地方设置一个缓存层。这可能需要花费很多时间，尤其是如果你经常这样做的话。

Cloudinary解决了这个问题。

它提供了一个媒体管理系统、云存储、即时资产操作和变换，等等。你唯一需要担心的是跟踪数据库中的资产。

实际上，这并不是真的。你甚至不需要担心这个问题，因为这个模块会为你处理。

提供Cloudinary配置

您需要提供Cloud名称、API密钥和API密钥。这些值是使模块能够与Cloudinary通信的核心要求。

将这些值放入您可能正在使用的任何YAML配置文件中，用于配置SilverStripe的其他部分。

我相信一个全新的SilverStripe安装会附带一个_config/mysite.yml文件。如果您找不到它，您可能已经将其重命名了。

MadeHQ\Cloudinary:
    cloud_name: 'CLOUDINARY_CLOUD_NAME'
    api_key: 'CLOUDINARY_API_KEY'
    api_secret: 'CLOUDINARY_API_SECRET'

创建数据库字段

该提供支持以下六个数据库字段

CloudinaryImage – 存储图片
CloudinaryMedia – 存储视频或音频¹
CloudinaryFile – 存储原始文件，如文档
CloudinaryMultiImage – 存储多个图片
CloudinaryMultiMedia – 存储多个视频或音频¹
CloudinaryMultiFile – 存储多个文件

如同使用其他数据库字段一样使用它们 – 在 $db 静态中添加条目

private static $db = [
    'MainImage' => 'CloudinaryImage',
    'BackgroundVideo' => 'CloudinaryMedia',
    'Brochure' => 'CloudinaryFile',
    'ImageGallery' => 'CloudinaryMultiImage',
    'VideoGallery' => 'CloudinaryMultiMedia',
    'Downloads' => 'CloudinaryMultiFile',
];

这些字段的优点在于它们的核心只是文本字段，因此没有关系或额外的表。

设置表单字段

除了 SiteTree 之外的所有扩展 DataObject 的类应自动根据数据库字段构建必要的表单字段。

对于包括 Page 在内的扩展 SiteTree 类，表单字段必须通过 getCMSFields 手动提供

use MadeHQ\Cloudinary\Forms\ImageField;
use MadeHQ\Cloudinary\Forms\MediaField;
use MadeHQ\Cloudinary\Forms\FileField;

// [...]
public function getCMSFields()
{
    $fields = parent::getCMSFields();

    // Single asset fields
    $fields->addToTab('Root.Main', ImageField::create('MainImage'));
    $fields->addToTab('Root.Main', MediaField::create('BackgroundVideo'));
    $fields->addToTab('Root.Main', FileField::create('Brochure'));

    // Multiple asset fields
    $fields->addToTab('Root.Main', ImageField::create('ImageGallery')->setMultiple(true));
    $fields->addToTab('Root.Main', MediaField::create('VideoGallery')->setMultiple(true));
    $fields->addToTab('Root.Main', FileField::create('Downloads')->setMultiple(true));

    return $fields;
}

附加方法

ImageField、MediaField 和 FileField 提供以下方法

支持的核心字段类型的补充字段列表

内联编辑器

WYSIWYG 中的默认媒体（ssmedia）处理程序被替换为使用云存储，而不是 Silverstripe 文件浏览器

内联编辑器的附加设置

有关以下内容的配置选项，请参阅 Cloudinary 的配置选项

`default_transformations`选项

设置为对象数组（自动在 JS 中包装在额外数组中）

\SilverStripe\Forms\HTMLEditor\HTMLEditorConfig::get('cms')
    ->setOptions([
        // This means that inline images will be limited to 1500px width by default (uses `limit` crop to keep aspect ratio)
        'default_transformations' => [['crop' => 'limit', 'width' => 1500]],
    ]);

渲染资产

为了给开发者更多控制资产使用方式的能力，此模块将简单地输出资产的 URL，而不是输出任何 HTML 标签。

没有简单的方法可以直接输出 HTML 标签，因为每个网站可能有不同的要求，仅仅输出一个 img 标签在现代网络开发中是不够的 – 我们现在必须考虑不同的屏幕尺寸、替代文件格式等。

简单地给开发者一个 URL，让他们自己决定如何处理。

图片

以原样渲染图像

<img src="$MainImage" alt="$MainImage.Description" />

此示例中的 description 是补充字段之一。

渲染一个调整大小的图像

<img src="$MainImage.Fill(640, 480)" alt="$MainImage.Description" />

渲染一个标签图片以获得更好的设备支持和艺术设计

<picture>
    <source media="(max-width: 420px)" srcset="$MainImage.Fill(420, 220), $MainImage.Fill(420, 220).DPR(2.0) 2x">
    <source media="(min-width: 421px) and (max-width: 768px)" srcset="$MainImage.Fill(708, 371), $MainImage.Fill(708, 371).DPR(2.0) 2x">
    <source media="(min-width: 769px) and (max-width: 1023px)" srcset="$MainImage.Fill(963, 504), $MainImage.Fill(963, 504).DPR(2.0) 2x">
    <source media="(min-width: 1024px) and (max-width: 1366px)" srcset="$MainImage.Fill(375, 196), $MainImage.Fill(375, 196).DPR(2.0) 2x">
    <source media="(min-width: 1367px) and (max-width: 1920px)" srcset="$MainImage.Fill(560, 293), $MainImage.Fill(560, 293).DPR(2.0) 2x">
    <source media="(min-width: 1921px)" srcset="$MainImage.Fill(1208, 632), $MainImage.Fill(1208, 632).DPR(2.0) 2x">
    <img src="$MainImage.Fill(420, 220)" alt="$MainImage.Description">
</picture>

支持的变换

视频

渲染一个跨浏览器的视频

<video autoplay muted>
    <source src="$MainVideo.FitByWidth(1024).Format('videoWebm')" type="video/webm">
    <source src="$MainVideo.FitByWidth(1024).Format('videoMp4')" type="video/mp4">
</video>

支持的变换

文件

渲染一个文件的下载链接

<a href="$Brochure" target="_blank">Download our brochure</a>

支持的变换

Cloudinary 不支持文件转换。

辅助方法

除了转换方法之外，该模块还公开了其他方法来帮助输出有关资产本身的信息。

其中一些是标准提供的，而另一些则可以通过内容编辑器填充，前提是已使用上面文档中的 ->setFields 方法启用了相应的字段。

全局配置

提供了一些全局配置选项，以防项目中的要求没有变化，或者为了进一步增强该模块。

这些可以放在您可能用于配置 SilverStripe 的 YAML 文件中，例如 _config/mysite.yml。

MadeHQ\Cloudinary\FieldType\DBImageResource:
    # Set the default output format of the images
    default_format: 'auto'
    # Set the default output quality of the images
    default_quality: 'auto'

MadeHQ\Cloudinary\Forms\BaseField:
    # Set the default number of files that can be selected for all the resources in it's multiple mode
    default_max_files: 25

MadeHQ\Cloudinary\Forms\ImageField:
    # Same as above but only for images
    default_max_files: 25
    # Set the list of available gravity options to choose from for images
    default_gravity_options:
        auto: 'Auto'
        auto:face: 'Auto (Face)'
        auto:faces: 'Auto (Faces)'
        auto:no_faces: 'Auto (No Faces)'
        center: 'Center'
        east: 'East'
        face: 'Face'
        faces: 'Faces'
        face:auto: 'Face (Auto)'
        faces:auto: 'Faces (Auto)'
        face:center: 'Face (Center)'
        faces:center: 'Faces (Center)'
        north: 'North'
        north_east: 'North East'
        north_west: 'North West'
        south: 'South'
        south_east: 'South East'
        south_west: 'South West'
        west: 'West'
    # Set the default supplementary fields that appear in the CMS
    default_fields:
        - title
        - description
        - credit

MadeHQ\Cloudinary\Forms\MediaField:
    # Same as above but only for media
    default_max_files: 25
    # Set the list of available gravity options to choose from for media
    default_gravity_options:
        auto: 'Auto'
        center: 'Center'
        east: 'East'
        north: 'North'
        north_east: 'North East'
        north_west: 'North West'
        south: 'South'
        south_east: 'South East'
        south_west: 'South West'
        west: 'West'
    # Set the default supplementary fields that appear in the CMS
    default_fields:
        - title
        - description

MadeHQ\Cloudinary\Forms\FileField:
    # Same as above but only for files
    default_max_files: 25
    # Set the default supplementary fields that appear in the CMS
    default_fields:
        - title

多资源字段

如上所述，通过在三个字段之一上使用 ->setMultiple(boolean $multiple) 方法启用了从 Cloudinary 选择多个资源的支持。这对于构建轮播图或提供下载列表的情况非常有用。

在核心上，这实际上只是提供每个选定的资源作为可以循环遍历的迭代器。列表中每个单个资源上的方法（无论是转换方法还是其他方法），如上所述，保持不变，但是启用此模式确实公开了 ->getLink() 或 $Link 方法，可以用来让最终用户下载所有资产的单个压缩文件。

示例用法

<ul>
    <% loop Downloads %>
        <li><a href="$Me" target="_blank">$Me.Title ($Me.FriendlyFileSize)</a></li>
    <% end_loop %>
</ul>

<p><a href="$Downloads.Link" target="_blank">Download all</a></p>

保留变换

默认情况下，模块会跳过对资源的任何用户应用转换，以使开发者能够更多地控制资产显示的方式。

背后的原因在于，开发者应该控制资产的总体外观，包括但不限于设置大小、裁剪、效果等。

但是，我们也意识到一些内容编辑者可能希望至少在一定程度上控制图像的显示方式，因此他们可能希望在插入资产之前使用媒体库来选择转换。

为了解决这一问题，一个合理的折衷方案是允许开发者指定内容编辑者可以应用的一组转换列表。

模块公开以下配置选项来实现这一功能

MadeHQ\Cloudinary\FieldType\DBImageResource:
    retain_transformations:
        - effect

MadeHQ\Cloudinary\FieldType\DBMediaResource:
    retain_transformations:
        - effect
        - video_sampling
        - keyframe_interval

目前只能保留之前文档中提到的支持的转换。随着我们添加更多支持的转换，这可能会发生变化。

主色

当选择图像时，模块将自动从中提取最突出的颜色。这作为ArrayList返回，因此可以在模板或PHP代码中轻松循环。这可以通过->getTopColours()或$TopColours访问。

ArrayList按颜色突出程度排序，最突出的是第一个，最不突出的是最后一个。

数组中的每个项目都由Predominance和一个提供一些方便的辅助函数的整洁的Colour对象组成，以便轻松操作颜色。

上述示例中使用的基色是#775313，所有增强都是通过10百分比进行的。

值得注意的是，此处所有返回颜色的方法都将返回一个Colour对象，因此您可以有效地执行链式操作，例如$Grayscale.Darken(10).FadeOut(10)。在PHP中使用时，可以将Colour强制转换为字符串以获取字面值。颜色的格式类型（rgb、hex等）将取决于原始输入颜色和/或操作方法。

该模块使用Iris提供颜色操作和转换功能。

贡献

此模块版本仍处于起步阶段。随着我们范围的扩大，我们将对其进行完善。如果您认为我们遗漏了某些内容，请随时提出问题，我们将很高兴进行审查并查看是否可以满足您的需求。

待办事项

进一步记录代码
更新README以包括关于转换方法的描述
更新README以包括示例截图
使补充字段易于扩展
减少React组件中的重复代码
提供更多转换
提供更好的颜色支持
在WYSIWYG中添加处理编辑/删除功能

迁移

如果您正在从先前（非小部件）版本的代码迁移，该代码使用了Silverstripe文件系统以及MadeHQ\Cloudinary\Model\ImageLink或MadeHQ\Cloudinary\Model\FileLink类来处理关系，那么您可以通过以下2个任务将数据迁移到新格式。注意：您需要在PHP文件中进行代码更改

步骤1

运行dev/tasks/MadeHQ-Cloudinary-Tasks-MigrationTaskStep1任务。这将为您提供使用MadeHQ\Cloudinary\Model\FileLink或其子类在has_one或many_many关系中使用文件的文件/类列表

步骤2

更新代码库，将has_one和many_many字段移动到db中，并使用适当的新字段类型（请参阅上面的创建数据库字段）。

其他所需的代码更改包括将调用::<ImageFieldName>()更改为::dbObject('<ImageFieldName>')（这可以通过::__call()魔术方法完成，但这留给个人处理）

步骤3

运行dev/build?flush=all以生成新字段。由于遗留字段是关系，因此无需担心字段名冲突。

步骤4

运行 dev/tasks/MadeHQ-Cloudinary-Tasks-MigrationTaskStep2 任务。这将从旧的关系中获取PublicID，并通过Admin API直接从Cloudinary请求文件数据。

注意：每小时可以向Cloudinary发送的API请求有2000次限制。目前没有重启动过程的方法，如果达到这个限制（可能需要考虑这个问题）。似乎可以通过联系Cloudinary来提高这个限制。

mademedia / silverstripe-cloudinary

维护者

详细信息

README

关于分支、版本和PHP版本的一些说明

目录

SilverStripe有资产管理系统，为什么还需要这个？

提供Cloudinary配置

创建数据库字段

设置表单字段

附加方法

内联编辑器

内联编辑器的附加设置

`default_transformations`选项

渲染资产

图片

支持的变换

视频

支持的变换

文件

支持的变换

辅助方法

全局配置

多资源字段

保留变换

主色

贡献

待办事项

迁移

步骤1

步骤2

步骤3

步骤4

mademedia / silverstripe-cloudinary

维护者

详细信息

README

关于分支、版本和PHP版本的一些说明

目录

SilverStripe有资产管理系统，为什么还需要这个？

提供Cloudinary配置

创建数据库字段

设置表单字段

附加方法

内联编辑器

内联编辑器的附加设置

default_transformations选项

渲染资产

图片

支持的变换

视频

支持的变换

文件

支持的变换

辅助方法

全局配置

多资源字段

保留变换

主色

贡献

待办事项

迁移

步骤1

步骤2

步骤3

步骤4

`default_transformations`选项