README

Tailor是一个命令行应用程序，可帮助您维护您的扩展。Tailor与TER REST API进行通信，并允许您注册新密钥、更新扩展信息和将新版本发布到扩展仓库。

内容

先决条件
安装
使用
在本地使用Tailor发布新版本
使用CI发布新版本
- Github actions工作流程
- GitLab管道
排除打包路径
所有可用命令概述
- 所有命令的通用选项
作者 & 许可证

先决条件

可以通过提供个人访问令牌来访问TER REST API。您可以在登录后直接在https://extensions.typo3.org/或直接使用Tailor创建此类令牌。

重要

要使用Tailor创建、刷新或吊销访问令牌，您必须添加您的TYPO3.org凭据（见下文）。尽管可以使用TYPO3.org凭据进行身份验证以执行所有命令，但强烈不建议这样做。这就是我们为什么为TER构建基于令牌的认证。

通过在项目根目录中创建一个.env文件或在您的系统中设置环境变量来提供您的凭据，以便此PHP脚本可以使用

TYPO3_API_TOKEN=<your-token>
TYPO3_API_USERNAME=<your-t3o-username>
TYPO3_API_PASSWORD=<your-t3o-password>

注意

要查看所有可用的环境变量概述，请查看.env.dist文件。

提示

您还可以在执行命令时直接添加环境变量。这将覆盖在.env文件中定义的任何变量。

示例

TYPO3_API_TOKEN="someToken" TYPO3_EXTENSION_KEY="ext_key" bin/tailor ter:details

如果someToken有效（未过期/吊销并且至少分配了extension:read作用域），则这将显示扩展ext_key的详细信息。

安装

使用composer将Tailor作为扩展的dev依赖项

composer req --dev typo3/tailor

使用

所有请求TER API的命令都提供-r, --raw选项。如果设置，则返回原始结果。这可以用于进一步处理，例如通过使用某些JSON处理器。

大多数命令需要扩展密钥才能工作。提供扩展密钥有多种可能性。以下是在检查的顺序

作为参数，例如./vendor/bin/tailor ter:details my_key
作为环境变量，TYPO3_EXTENSION_KEY=my_key
在您的composer.json中，[extra][typo3/cms][extension-key] = 'my_key'

这意味着，即使您已定义全局扩展密钥，无论是作为环境变量还是您的composer.json中的内容，您仍然可以通过在命令中添加所需的扩展密钥作为参数来运行所有针对不同扩展的命令。

注意

如果没有定义扩展密钥，无论是作为参数、环境变量，还是在您的 composer.json 中，都需要设置扩展密钥的命令将会抛出异常。

管理您的个人访问令牌

使用 ter:token:create 命令来创建新的令牌

./vendor/bin/tailor ter:token:create --name="token for my_extension" --extensions=my_extension

结果看起来像这样

Token type: bearer
Access token: eyJ0eXAOiEJKV1QiLCJhb
Refresh token: eyJ0eXMRxHRaF4hIVrEtu
Expires in: 604800
Scope: extension:read,extension:write
Extensions: my_extension

如您所见，这将创建一个仅对扩展 my_extension 有效的访问令牌。由于没有提供 --scope 选项，作用域设置为 extension:read,extension:write，这是默认设置。同样，过期日期也可以通过 --expires 选项设置。

如果令牌即将过期，请使用 ter:token:refresh 来刷新它

./vendor/bin/tailor ter:token:refresh eyJ0eXMRxHRaF4hIVrEtu

这将生成新的访问令牌和刷新令牌，并使用创建时设置的相同选项。

要永久吊销访问令牌，请使用 ter:token:revoke

./vendor/bin/tailor ter:token:revoke eyJ0eXAOiEJKV1QiLCJhb

注册新的扩展密钥

要注册新扩展，请使用 ter:register 并提供所需的扩展密钥作为参数

./vendor/bin/tailor ter:register my_extension

这将注册密钥 my_extension 并返回以下确认信息

Key: my_extension
Owner: your_username

更新扩展文件中的版本

在发布新版本之前，您必须更新扩展中的 ext_emconf.php 文件中的版本。这可以使用 set-version 命令完成。

./vendor/bin/tailor set-version 1.2.0

如果您的扩展还包含 Documentation/Settings.cfg 文件，该命令也会更新其中的 release 和 version 信息。您可以通过使用 --no-docs 或设置环境变量 TYPO3_DISABLE_DOCS_VERSION_UPDATE=1 来禁用此功能。

提示

您还可以使用 --path 选项来指定扩展的位置。如果没有指定，当前工作目录将搜索 ext_emconf.php 文件。

注意

只有当版本已经在您的 ext_emconf.php 中存在时，版本才会更新。该命令不会添加它。

将扩展的新版本发布到TER

您可以使用 ter:publish 命令发布扩展的新版本。因此，提供扩展密钥和版本号作为参数，后跟扩展目录的路径或工件（扩展的压缩版本）。后者可以是本地文件或远程文件。

使用 --path

./vendor/bin/tailor ter:publish 1.2.0 my_extension --path=/path/to/my_extension

使用本地 --artefact

./vendor/bin/tailor ter:publish 1.2.0 my_extension --artefact=/path/to/any-zip-file/my_extension.zip

使用远程 --artefact

./vendor/bin/tailor ter:publish 1.2.0 my_extension --artefact=https://github.com/my-name/my_extension/archive/1.2.0.zip

使用根目录

./vendor/bin/tailor ter:publish 1.2.0 my_extension

如果扩展密钥已在环境变量或您的 composer.json 中定义，则也可以省略。因此，使用当前根目录，整个命令简化为

./vendor/bin/tailor ter:publish 1.2.0

重要

默认情况下，一些目录和文件会被排除在打包之外。有关排除路径从打包中的更多信息，请参阅下文。

注意

REST API，就像 TER 一样，需要一个上传注释来设置。这可以通过使用 --comment 选项来实现。如果没有设置，Tailor 将自动使用 Updated extension to <version> 作为注释。

创建扩展的本地工件

您可以使用 create-artefact 命令生成扩展的本地工件。这将生成一个可用于上传到 TER 的压缩归档（请注意，此命令不包括在 ter:publish 命令中，请参阅该命令）。

提供版本号和扩展密钥作为参数，后跟扩展目录的路径或工件（扩展的压缩版本）。后者可以是本地文件或远程文件。

使用 --path

./vendor/bin/tailor create-artefact 1.2.0 my_extension --path=/path/to/my_extension

使用本地 --artefact

./vendor/bin/tailor create-artefact 1.2.0 my_extension --artefact=/path/to/any-zip-file/my_extension.zip

使用远程 --artefact

./vendor/bin/tailor create-artefact 1.2.0 my_extension --artefact=https://github.com/my-name/my_extension/archive/1.2.0.zip

使用根目录

./vendor/bin/tailor create-artefact 1.2.0 my_extension

如果扩展密钥已在环境变量或您的 composer.json 中定义，则也可以省略。因此，使用当前根目录，整个命令简化为

./vendor/bin/tailor create-artefact 1.2.0

重要

默认情况下，一些目录和文件会被排除在打包之外。有关排除路径从打包中的更多信息，请参阅下文。

更新扩展元信息

您可以使用 ter:update 命令更新扩展元信息，例如 composer 名称，或相关的标签。

要更新 composer 名称

./vendor/bin/tailor ter:update my_extension --composer=vender/my_extension

要更新标签

./vendor/bin/tailor ter:update my_extension --tags=some-tag,another-tag

请使用 ./vendor/bin/tailor ter:update -h 来查看所有可用选项的完整列表。

重要

此命令设置的选项将覆盖现有数据。因此，如果您只想添加另一个标签，您必须同时添加当前标签和新标签。您可以使用 ter:details 来获取当前状态。

将扩展所有权转让给其他用户

可以将您的扩展之一转移到另一个用户。因此，请使用ter:transfer命令，并提供要转移的扩展密钥和接收者的TYPO3.org用户名。

由于您在此之后将无法访问该扩展，在向REST API发送订单之前，命令将要求您确认。

./vendor/bin/tailor ter:transfer some_user my_extension

这将把扩展my_extension转移到用户some_user，并返回以下确认信息。

Key: my_extension
Owner: some_user

提示

对于自动化工作流程，可以使用-n, --no-interaction选项跳过确认。

删除/放弃扩展

您可以使用Tailor轻松删除或放弃扩展，只需使用ter:delete命令。这将完全删除扩展，或者如果扩展仍有公共版本，则仅放弃它。

由于您在此之后将无法访问该扩展，在向REST API发送订单之前，命令将要求您确认。

./vendor/bin/tailor ter:delete my_extension

这将删除或放弃扩展my_extension。

提示

对于自动化工作流程，可以使用-n, --no-interaction选项跳过确认。

在TER上查找和筛选扩展

Tailor不仅可以用于管理您的扩展，还可以用于查找其他扩展。因此，通过添加一些过滤器使用ter:find。

./vendor/bin/tailor ter:find
./vendor/bin/tailor ter:find --typo3-version=9
./vendor/bin/tailor ter:find --typo3-author=some_user

第一个命令将查找所有公共扩展。第二个和第三个命令将只返回与过滤器匹配的扩展。在这种情况下，与TYPO3版本9兼容或由some_user拥有。

要限制/分页结果，可以使用选项--page和--per_page。

./vendor/bin/tailor ter:find --page=3 --per_page=20

特定扩展的详细信息

您还可以使用ter:details命令请求有关特定扩展的更多信息。

./vendor/bin/tailor ter:details my_extension

这将返回有关扩展my_extension的详细信息，例如当前版本、作者、一些元信息等。类似于extension.typo3.org上的扩展详细信息页面。

特定扩展版本的详细信息

如果您想了解有关扩展特定版本的详细信息，可以使用ter:version。

./vendor/bin/tailor ter:version 1.0.0 my_extension

这将返回有关扩展my_extension的版本1.0.0的详细信息。

扩展所有版本的详细信息

您还可以使用ter:versions获取有关扩展所有版本的详细信息。

./vendor/bin/tailor ter:versions my_extension

这将返回有关扩展my_extension所有版本的详细信息。

在本地使用Tailor发布新版本

步骤1：更新扩展文件中的版本。

./vendor/bin/tailor set-version 1.5.0

步骤2：提交更改并添加标签。

git commit -am "[RELEASE] A new version was published"
git tag -a 1.5.0

步骤3：将此推送到远程仓库。

git push origin --tags

步骤4：将此版本推送到TER。

./vendor/bin/tailor ter:publish 1.5.0

注意

set-version和ter:publish都提供了指定扩展位置的选项。如果，如上面的示例所示，没有设置，Tailor将自动使用您当前的工作目录。

使用CI发布新版本

您还可以将Tailor集成到GitHub工作流程或GitLab流水线中。因此，上面示例中的步骤1、步骤2和步骤3是相同的。步骤4可以由您的集成完成。

请参阅以下示例，说明GitHub工作流程和GitLab流水线中此类集成的可能外观。

Github actions工作流程

工作流程仅在推送新标签时执行。这可以是使用上面示例中的步骤3完成，或者通过创建新的GitHub发布版，这将添加新标签。

此外，工作流程还需要设置GitHub秘密TYPO3_EXTENSION_KEY和TYPO3_API_TOKEN。在“设置 -> Secrets -> 新仓库秘密”中添加它们。

注意

如果您的composer.json文件在[extra][typo3/cms][extension-key] = 'my_key'处包含扩展密钥（这始终是最佳实践），则下面的GitHub操作示例中不需要TYPO3_EXTENSION_KEY秘密和分配，Tailor将自动获取。

版本将从标签自动获取并验证以匹配所需模式。

从步骤2中使用的提交信息用作发布评论。如果为空，则使用静态文本。

要查看以下工作流程的实际操作，请参阅tailor_ext示例扩展。

name: publish
on:
  push:
    tags:
      - '*'
jobs:
  publish:
    name: Publish new version to TER
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-20.04
    env:
      TYPO3_EXTENSION_KEY: ${{ secrets.TYPO3_EXTENSION_KEY }}
      TYPO3_API_TOKEN: ${{ secrets.TYPO3_API_TOKEN }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Check tag
        run: |
          if ! [[ ${{ github.ref }} =~ ^refs/tags/[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}$ ]]; then
            exit 1
          fi

      - name: Get version
        id: get-version
        run: echo "version=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_ENV

      - name: Get comment
        id: get-comment
        run: |
          readonly local comment=$(git tag -n10 -l ${{ env.version }} | sed "s/^[0-9.]*[ ]*//g")

          if [[ -z "${comment// }" ]]; then
            echo "comment=Released version ${{ env.version }} of ${{ env.TYPO3_EXTENSION_KEY }}" >> $GITHUB_ENV
          else
            {
              echo 'comment<<EOF'
              echo "$comment"
              echo EOF
            } >> "$GITHUB_ENV"
          fi

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 7.4
          extensions: intl, mbstring, json, zip, curl
          tools: composer:v2

      - name: Install tailor
        run: composer global require typo3/tailor --prefer-dist --no-progress --no-suggest

      - name: Publish to TER
        run: php ~/.composer/vendor/bin/tailor ter:publish --comment "${{ env.comment }}" ${{ env.version }}

重要

如果您使用的是以v开头的标签，则上述示例需要调整。

在步骤检查标签中的正则表达式应为

^refs/tags/v[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}$

在第 获取版本 步骤中，输出格式应该是

${GITHUB_REF#refs/tags/v}

在第 获取注释 步骤中，变量声明应该是

$(git tag -n10 -l v${{ env.version }} | sed "s/^v[0-9.]*[ ]*//g")

来自TYPO3社区的GitHub动作

此外，为了进一步简化您的流程，您还可以使用来自TYPO3社区成员Tomas Norre的GitHub动作 typo3-uploader-ter。有关使用方法的更多信息，请参阅相应的 README。

GitLab管道

只有当推送新标签时才会执行作业。上传注释来自标签中的消息。

此外，作业还需要GitLab变量 TYPO3_EXTENSION_KEY 和 TYPO3_API_TOKEN 被设置。

注意

如果您的 composer.json 文件包含您的扩展密钥，您可以在GitLab管道中移除 TYPO3_EXTENSION_KEY 变量、检查和赋值，因为Tailor会自动获取此密钥。

变量 CI_COMMIT_TAG 是由GitLab自动设置的。

"Publish new version to TER":
  stage: release
  image: composer:2
  only:
    - tags
  before_script:
    - composer global require typo3/tailor
  script:
    - >
      if [ -n "$CI_COMMIT_TAG" ] && [ -n "$TYPO3_API_TOKEN" ] && [ -n "$TYPO3_EXTENSION_KEY" ]; then
        echo -e "Preparing upload of release ${CI_COMMIT_TAG} to TER\n"
        # Cleanup before we upload
        git reset --hard HEAD && git clean -fx
        # Upload
        TAG_MESSAGE=`git tag -n10 -l $CI_COMMIT_TAG | sed 's/^[0-9.]*[ ]*//g'`
        echo "Uploading release ${CI_COMMIT_TAG} to TER"
        /tmp/vendor/bin/tailor ter:publish --comment "$TAG_MESSAGE" "$CI_COMMIT_TAG" "$TYPO3_EXTENSION_KEY"
      fi;

排除打包路径

默认情况下，一些目录和文件被排除在打包之外。您可以在 conf/ExcludeFromPackaging.php 中找到配置。

如果您喜欢，您还可以使用自定义配置。只需将自定义配置文件的路径添加到环境变量 TYPO3_EXCLUDE_FROM_PACKAGING 中。此文件必须返回一个包含键 directories 和 files 的 array，位于根级别。

所有可用命令概述

所有命令的通用选项

-r, --raw 以原始对象（例如json）返回结果 - 仅适用于请求TER API的命令
-h, --help 显示帮助信息
-q, --quiet 不输出任何消息
-v, --version 显示CLI应用程序的版本
-n, --no-interaction 不询问任何交互式问题
-v|vv|vvv, --verbose 增加消息的详细程度：1为常规输出，2为更详细的输出，3为调试
--ansi 强制ANSI输出
--no-ansi 禁用ANSI输出

作者 & 许可证

由Benni Mack和Oliver Bartsch创建。

MIT许可，请参阅LICENSE

typo3 /

维护者

详细信息