Download the PHP package typo3/tailor without Composer

Tailor

Tailor is a CLI application to help you maintain your extensions. Tailor talks with the TER REST API and enables you to register new keys, update extension information and publish new versions to the extension repository.

Contents

• Prerequisites
• Installation
• Usage
  • Manage your personal access token
  • Register a new extension key
  • Update the version in your extension files
  • Publish a new version of an extension to TER
  • Create a local artefact of an extension
  • Update extension meta information
  • Transfer ownership of an extension to another user
  • Delete / abandon an extension
  • Find and filter extensions on TER
  • Specific extension details
  • Specific extension version details
  • Details for all versions of an extension
• Publish a new version using tailor locally
• Publish a new version using your CI
  • Github actions workflow
  • GitLab pipeline
• Exclude paths from packaging
• Overview of all available commands
  • General options for all commands
• Author & License

Prerequisites

The TER REST API can be accessed providing a personal access token. You can create such token either on https://extensions.typo3.org/ after you've logged in, or directly using Tailor.

[!IMPORTANT] To create, refresh or revoke an access token with Tailor, you have to add your TYPO3.org credentials (see below). Even if it is possible to execute all commands using the TYPO3.org credentials for authentication, it is highly discouraged. That's why we have built token based authentication for the TER.

Provide your credentials by either creating a .env file in the project root folder or setting environment variables through your system to this PHP script:

[!NOTE] For an overview of all available environment variables, have a look at the .env.dist file.

[!TIP] You can also add environment variables directly on executing a command. This overrides any variable, defined in the .env file.

Example:

This will display the extension details for extension ext_key if someToken is valid (not expired/revoked and having at least the extension:read scope assigned).

Installation

Use Tailor as a dev dependency via composer of your extensions:

Usage

All commands, requesting the TER API, provide the -r, --raw option. If set, the raw result will be returned. This can be used for further processing e.g. by using some JSON processor.

Most of the commands require an extension key to work with. There are multiple possibilities to provide an extension key. These are - in the order in which they are checked:

• As argument, e.g. ./vendor/bin/tailor ter:details my_key
• As environment variable, TYPO3_EXTENSION_KEY=my_key
• In your composer.json, [extra][typo3/cms][extension-key] = 'my_key'

This means, even if you have an extension key defined globally, either as environment variable or in your composer.json, you can still run all commands for different extensions by adding the desired extension key as argument to the command.

[!NOTE] If no extension key is defined, neither as an argument, as environment variable, nor in your composer.json, commands which require an extension key to be set, will throw an exception.

Manage your personal access token

Use the ter:token:create command to create a new token:

The result will look like this:

As you can see, this will create an access token which is only valid for the extension my_extension. The scopes are set to extension:read,extension:write since this is the default if option --scope is not provided. The same applies to the expiration date which can be set with the option --expires.

If the token threatens to expire, refresh it with ter:token:refresh:

This will generate new access and refresh tokens with the same options, initially set on creation.

To revoke an access token irretrievably, use ter:token:revoke:

Register a new extension key

To register a new extension, use ter:register by providing your desired extension key as argument:

This registers the key my_extension and returns following confirmation:

Update the version in your extension files

Prior to publishing a new version, you have to update the version in your extensions ext_emconf.php file. This can be done using the set-version command.

If your extension also contains a Documentation/guides.xml or Documentation/Settings.cfg file, the command will also update the release and version information in it. You can disable this feature by either using --no-docs or by setting the environment variable TYPO3_DISABLE_DOCS_VERSION_UPDATE=1.

[!TIP] It's also possible to use the --path option to specify the location of your extension. If not given, your current working directory is search for the ext_emconf.php file.

[!NOTE] The version will only be updated if already present in your ext_emconf.php. It won't be added by this command.

Publish a new version of an extension to TER

You can publish a new version of your extension using the ter:publish command. Therefore, provide the extension key and version number as arguments followed by the path to the extension directory or an artefact (a zipped version of your extension). The latter can be either local or a remote file.

Using --path:

Using a local --artefact:

Using a remote --artefact:

Using the root direcotry:

If the extension key is defined as environment variable or in your composer.json, it can also be skipped. So using the current root directory the whole command simplifies to:

[!IMPORTANT] A couple of directories and files are excluded from packaging by default. Read more about excluding paths from packaging below.

[!NOTE] The REST API, just like the the TER, requires an upload comment to be set. This can be achieved using the --comment option. If not set, Tailor will automatically use Updated extension to <version> as comment.

Create a local artefact of an extension

You can generate a local artefact of your extension using the create-artefact command. This will generate a zip archive ready to be uploaded to TER (which is not covered by this command, have a look at the ter:publish command instead).

Provide the version number and extension key as arguments followed by the path to the extension directory or an artefact (a zipped version of your extension). The latter can be either local or a remote file.

Using --path:

Using a local --artefact:

Using a remote --artefact:

Using the root directory:

If the extension key is defined as environment variable or in your composer.json, it can also be skipped. So using the current root directory the whole command simplifies to:

[!IMPORTANT] A couple of directories and files are excluded from packaging by default. Read more about excluding paths from packaging below.

Update extension meta information

You can update the extension meta information, such as the composer name, or the associated tags with the ter:update command.

To update the composer name:

To update the tags:

Please use ./vendor/bin/tailor ter:update -h to see the full list of available options.

[!IMPORTANT] All options set with this command will overwrite the existing data. Therefore, if you, for example, just want to add another tag, you have to add the current ones along with the new one. You can use ter:details to get the current state.

Transfer ownership of an extension to another user

It's possible to transfer one of your extensions to another user. Therefore, use the ter:transfer command providing the extension key to be transferred and the TYPO3.org username of the recipient.

Since you won't have any access to the extension afterwards, the command asks for your confirmation before sending the order to the REST API.

This transfers the extension my_extension to the user some_user and returns following confirmation:

[!TIP] For automated workflows the confirmation can be skipped with the -n, --no-interaction option.

Delete / abandon an extension

You can easily delete / abandon extensions with Tailor using the ter:delete command. This either removes the extension entirely or just abandons it if the extension still has public versions.

Since you won't have any access to the extension afterwards, the command asks for your confirmation before sending the order to the REST API.

This will delete / abandon the extension my_extension.

[!TIP] For automated workflows the confirmation can be skipped with the -n, --no-interaction option.

Find and filter extensions on TER

Tailor can't only be used for managing your extensions but also to find others. Therefore, use ter:find by adding some filters:

First command will find all public extensions. The second and third one will only return extensions which match the filter. In this case being compatible with TYPO3 version 9 or owned by some_user.

To limit / paginate the result, you can use the options --page and --per_page:

Specific extension details

You can also request more details about a specific extension using the ter:details command:

This will return details about the extension my_extension like the current version, the author, some meta information and more. Similar to the extension detail page on extension.typo3.org.

Specific extension version details

If you like to get details about a specific version of an extension, ter:version can be used:

This will return details about version 1.0.0 of extension my_extension.

Details for all versions of an extension

You can also get the details for all versions of an extension with ter:versions:

This will return the details for all version of the extension my_extension.

Publish a new version using tailor locally

Step 1: Update the version in your extension files

Step 2: Commit the changes and add a tag

Step 3: Push this to your remote repository

Step 4: Push this version to TER

[!NOTE] Both set-version and ter:publish provide options to specify the location of your extension. If, like in the example above, non is set, Tailor automatically uses your current working directory.

Publish a new version using your CI

You can also integrate tailor into you GitHub workflow respectively your GitLab pipeline. Therefore, Step 1, Step 2 and Step 3 from the above example are the same. Step 4 could then be done by your integration.

Please have a look at the following examples describing how such integration could look like for GitHub workflows and GitLab pipelines.

Github actions workflow

The workflow will only be executed when pushing a new tag. This can either be done using Step 3 from above example or by creating a new GitHub release which will also add a new tag.

The workflow furthermore requires the GitHub secrets TYPO3_EXTENSION_KEY and TYPO3_API_TOKEN to be set. Add them at "Settings -> Secrets -> New repository secret".

[!NOTE] If your composer.json file contains the extension key at [extra][typo3/cms][extension-key] = 'my_key' (this is good practice anyway), the TYPO3_EXTENSION_KEY secret and assignment in the below GitHub action example is not needed, tailor will pick it up.

The version is automatically fetched from the tag and validated to match the required pattern.

The commit message from Step 2 is used as the release comment. If it's empty, a static text will be used.

To see the following workflow in action, please have a look at the tailor_ext example extension.

[!IMPORTANT] If you're using tags with a leading v the above example needs to be adjusted.

1. The regular expression in step Check tag should be:

2. The output format in step Get version should be:

3. The variable declaration in step Get comment should be:

GitHub actions from TYPO3 community

Additionally, to further simplify your workflow, you can also use the typo3-uploader-ter GitHub action from TYPO3 community member Tomas Norre. For more information about the usage, please refer to the corresponding README.

GitLab pipeline

The job will only be executed when pushing a new tag. The upload comment is taken from the message in the tag.

The job furthermore requires the GitLab variables TYPO3_EXTENSION_KEY and TYPO3_API_TOKEN to be set.

[!NOTE] If your composer.json file contains your extension key, you can remove the TYPO3_EXTENSION_KEY variable, the check and the assignment in the GitLab pipeline, since Tailor automatically fetches this key then.

The variable CI_COMMIT_TAG is set by GitLab automatically.

Exclude paths from packaging

A couple of directories and files are excluded from packaging by default. You can find the configuration in conf/ExcludeFromPackaging.php.

If you like, you can also use a custom configuration. Just add the path to your custom configuration file to the environment variable TYPO3_EXCLUDE_FROM_PACKAGING. This file must return an array with the keys directories and files on root level.

Overview of all available commands

General options for all commands

• -r, --raw Return result as raw object (e.g. json) - Only for commands, requesting the TER API
• -h, --help Display help message
• -q, --quiet Do not output any message
• -v, --version Display the CLI applications' version
• -n, --no-interaction Do not ask any interactive question
• -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
• --ansi Force ANSI output
• --no-ansi Disable ANSI output

Author & License

Created by Benni Mack and Oliver Bartsch.

MIT License, see LICENSE