README

Neos 的 pixx.io 适配器

此 Flow 包允许您将存储在 pixx.io 中的资产（例如图片和其他文档）用作原生 Neos 资产。

关于 pixx.io

pixx.io 提供了一种智能的数字资产管理解决方案。该软件使处理图片、图形和视频文件变得更加容易。pixx.io 安全、高效且易于理解和操作。

主要功能

• 通过自己的后端模块进行身份验证设置
• 无缝集成到 Neos 媒体浏览器中
• 自动从 pixx.io 导入和清理媒体资产

安装

通过 Composer 将 pixx.io 连接器作为常规 Flow 包安装。对于您的现有项目，只需将 flownative/neos-pixxio 包含到您的 Flow 或 Neos 分发版的依赖项中即可。

composer require flownative/neos-pixxio

安装后，您需要运行数据库迁移

./flow doctrine:migrate

启用 pixx.io API 访问

API 访问由三个组件配置

1. 一个包含客户特定服务端点 URL 的设置
2. 提供 pixx.io API 密钥的设置
3. 提供 pixx.io 用户刷新令牌的设置

要获取 API 端点和 API 密钥所需的值，请联系您的 pixx.io 支持联系人。

首先通过添加 URL 到您的设置中定义客户特定的服务端点

Neos:
  Media:
    assetSources:
      'flownative-pixxio':
        assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource'
        assetSourceOptions:
          apiEndpointUri: 'https://flownative.pixxio.media/cgi-bin/api/pixxio-api.pl'

您可能只需要将 "flownative" 替换为我们自己的子域名。

接下来，添加您想要连接到 Neos 的 pixx.io API 密钥和刷新令牌

Neos:
  Media:
    assetSources:
      'flownative-pixxio':
        assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource'
        assetSourceOptions:
          apiEndpointUri: 'https://flownative.pixxio.media/cgi-bin/api/pixxio-api.pl'
          apiKey: 'abcdef123456789'
          sharedRefreshToken: 'A3ZezMq6Q24X314xbaiq5ewNE5q4Gt'

在提交和部署这些更改后，您可以登录 Neos 后端并导航到 pixx.io 后端模块以验证您的设置。

如果您希望为登录的 Neos 用户创建单独的 pixx.io 用户，您可以将自己的 "刷新令牌" 复制粘贴到后端模块中找到的表单中，并将其与您的 Neos 用户一起存储。

如果一切正常，Neos 将报告连接成功（如果不正常，您将看到一个包含更多详细信息的错误消息）。

其他配置选项

在导入过程中，Neos 尝试使用原始文件的中等尺寸版本，而不是上传到 pixx.io 的高分辨率文件。这极大地提高了导入速度，并在大多数情况下产生良好的结果。此外，这种方法可以使一些格式（例如 Adobe Photoshop）在 Neos 中无缝使用，而无需事先将它们转换为兼容网页的图像格式。

尽管如此，您可以通过类似以下设置中的条目来配置此插件，使其始终使用高分辨率原始文件进行导入。默认情况下，像 SVG 或 PDF 这样的格式就是这样导入的。您可以通过类似设置添加更多类型。

Neos:
  Media:
    assetSources:
      'flownative-pixxio':
        assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource'
        assetSourceOptions:
          mediaTypes:
            'image/svg+xml':
              usePixxioThumbnailAsOriginal: true
            'application/pdf':
              usePixxioThumbnailAsOriginal: true

有时 API 客户端需要对 TLS 连接进行额外的配置，例如自定义超时或证书。请参阅：http://docs.guzzlephp.org/en/6.5/request-options.html

Neos:
  Media:
    assetSources:
      'flownative-pixxio':
        assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource'
        assetSourceOptions:
          apiClientOptions:
            'verify': '/path/to/cert.pem'

使用文件 ImageOptions 参数

通过配置，您可以设置返回图像必须具有的尺寸。尺寸由以下键定义

• thumbnailUri 用于媒体浏览器列表
• previewUri 用于资产的详细页面
• originalUri 用于下载资产

默认情况下，配置是

Neos:
  Media:
    assetSources:
      'flownative-pixxio':
        assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource'
        assetSourceOptions:
          imageOptions:
            thumbnailUri:
              width: 400
              height: 400
              quality: 90
              crop: false
            previewUri:
              width: 1500
              height: 1500
              quality: 90
            originalUri:
              sizeMax: 1920
              quality: 90

可以通过指定特定的预设键，从您自己的包配置中覆盖每个imageOptions。

默认情况下，Pixx.io 返回的是裁剪格式的资产。在这种情况下，当编辑器在媒体浏览器列表中查看时，无法看到资产是横向还是纵向。通过设置 crop: false，图片将以非裁剪版本返回，编辑器可以查看资产的朝向。

清理未使用资产

每当在Neos中使用pixx.io资产时，媒体文件将自动复制到内部Neos资产存储。只要该媒体在网站上某处使用，Neos就会标记该资产为正在使用。当资产不再使用时，可以从内部存储中删除二进制数据和相应的元数据。虽然这不是自动发生的，但它可以通过一个重复任务，如cron-job，轻松自动化。

为了清理未使用的资产，只需按需运行以下命令

./flow media:removeunused --asset-source flownative-pixxio

如果您想通过cron-job调用此命令，可以添加两个额外的标志，使此命令非交互式

./flow media:removeunused --quiet --assume-yes --asset-source flownative-pixxio

自动标记

此插件还提供自动标记功能。当启用自动标记时，Neos会自动标记当前使用的资产，并使用用户定义的关键词。当资产在Neos中不再使用时，此关键词将被删除。此关键词应用于pixx.io媒体库中的实际文件/资产，帮助编辑器了解哪些资产正在由Neos使用。

自动标记的配置如下

Neos:
  Media:
    assetSources:
      'flownative-pixxio':
        assetSource: 'Flownative\Pixxio\AssetSource\PixxioAssetSource'
        assetSourceOptions:
          autoTagging:
            enable: true
            inUseTag: 'your-custom-tag'

由于Neos目前无法在运行时可靠地处理自动标记，因此必须通过命令行命令来完成这项工作。只需运行以下命令为标记新资产和从不再使用的资产中删除标记

./flow pixxio:tagusedassets

Tagging used assets of asset source "flownative-pixxio" via Pixxio API:
  (tagged)  dana-devolk-1348553-unsplash 358 (1)
   tagged   azamat-zhanisov-1348039-unsplash 354 (1)
  (tagged)  tim-foster-1345174-unsplash 373 (1)
   removed  some-coffee 28 (0)
  (tagged)  nikhita-s-615116-unsplash 368 (1)

建议通过cron-job运行此命令，最好与 media:removeunused 命令结合使用。运行 removeunused-命令非常重要之后运行标记命令，因为否则在pixx.io媒体库中删除的图片将不会被取消标记。

注意
到目前为止，自动标记功能并未针对性能进行优化。该命令仅遍历所有从pixx.io导入的资产，并检查是否需要更新标记。

从pixx.io到Neos的分类映射

pixx.io提供了分类来以文件夹结构组织资产。这些可以映射到Neos中的资产集合和标签，使其对用户可见。

注意
pixx.io资产源声明为只读。Neos不会在UI中显示只读资产源的资产集合。从Neos 7.3.0版本开始已更改，具体请参阅neos/neos-development-collection#3481

如果您想使用较旧版本的Neos，可以使用带有cweagans/composer-patches的PR或将其调整的模板复制到您的项目中，并使用Views.yaml来激活它。

分类导入的配置如下

Flownative:
  Pixxio:
    mapping:
      # map "categories" from pixx.io to Neos
      categoriesMaximumDepth: 2         # only include the first two levels of categories
      categories:
        'People/Employees':
          asAssetCollection: false      # ignore this category, put more specific patterns first
        'People*':                      # the category "path" in pixx.io, shell-style globbing is supported
          asAssetCollection: true       # map to an asset collection named after the category

• 使用的是从pixx.io API使用的分类标识符，不带前导斜杠
• asAssetCollection设置为true将分类作为与分类名称相同的资产集合公开。

之后，运行以下命令来更新资产集合，最好在cronjob中运行以保持最新

./flow pixxio:importcategoriesascollections

要检查给定分类会导入什么，可以使用详尽的dry-run

$ ./flow pixxio:importcategoriesascollections --quiet 0 --dry-run 1
Importing categories as asset collections via pixx.io API
o Dokumentation
= Kunde A
= Kunde A/Projekt 1
o Kunde A/Projekt 1/Copy
o Kunde A/Projekt 1/Design
+ Kunde A/Projekt 2
o Kunde A/Projekt 2/Copy
o Kunde A/Projekt 2/Design
o Marketing
o home
o home/Doe_John
Import done.

上述操作会添加 "Kunde A/Projekt 2"，标记为 "=" 的项目已存在，其他所有内容将被忽略。

背景和演示

致谢和许可证

此插件的第一个版本由 pixx.io 赞助，其初始版本由 Flownative 的 Robert Lemke 开发。

查看 LICENSE 获取许可证详细信息。