8 Ways to Publish Your TER TYPO3 Extensions

8 Ways to Publish Your TER TYPO3 Extensions

Amazing! You’ve made a great decision to OpenSource contribute to the TER TYPO3 Extensions, I appreciate it! Are you looking for help to publish the TER TYPO3 extension? In this article, You will find a step-by-step guide to release manuals or automize your extension to TER.

TYPO3 Extensions Repository (aks TER) is a centralized place where many TYPO3 agencies and developers develop and publish their TER TYPO3 extensions - As give back to OpenSource. For productive work of the TYPO3 Developer, publishing, and deployment of extension to TER should be easy and convenient. That’s why I’m writing this article to help you - to save your time. You just focus on the development of your TER TYPO3 extensions, and let’s automate the publish :)

Our App Store is Called TER - and It's Free!
-TYPO3 GmbH

Create TYPO3.org Account

To publish your TYPO3 extensions at TER, You will need to create an account at TYPO3.org.

Step 1. Land to My.TYPO3.org - A central for all TYPO3 sites https://my.typo3.org/register

Step 2. Login at Extensions.TYPO3.org

Register TYPO3 Extension Key

Before you start to develop your TYPO3 extension, It’s essential to check, register and validate your TYPO3 extension key.

Step 1. Click on “My Extensions” from Main-menu https://extensions.typo3.org/my-extensions/

Step 2. Go to the “Register extension key.”

Initiate Git Public Repository

90% of TYPO3 developers use Git repositories to develop and well-maintained their TYPO3 extensions for public TER as well as private projects too.

What Are Recommended Git Tools?

  • Github.com
  • Gitlab.com
  • Bitbucket.com

Why Git repositories for TER Extension?

  • Easily maintain code repositories
  • Automatically publish TYPO3 extension to TER
  • The community can contribute code to your TYPO3 extension
  • Code review with Lints
  • Allow people to use the master repository
  • And, so on!

Prepare TYPO3 Documentation

Well, it’s not the technical part, but very important for the people who want to use your TYPO3 extensions.

What should we include in TYPO3 documentation?

  • Introduction
  • Screenshots
  • Installation & Configuration
  • Users Guide
  • Integrator Guide
  • Developer Guide (if any)
  • Support
  • FAQ

Option 1. Official Docs.TYPO3.org

TYPO3 Community have an excellent platform for the documentation of the core as well as for the TER TYPO3 extensions too eg., https://docs.typo3.org/p/georgringer/news/8.4/en-us/

Just create the “Documentation” folder into extension, and start to write documentation in RST format.

Read the step-by-step guide at How to Document an Extension.

Option 2. Your External Documentation

Many developers just want to make simple-own documentation without follow-up RST format of docs.typo3.org; You can simply create documentation in the below ways.

Using README.md at your Git repository

  • Write a blog about the extension.
  • Use Wiki at your Git repository.
  • Etc.

For this case, You will need to provide a documentation URL at your extension as below

Issues Management

It’s a good idea to provide a bug-tracker or issues management system to the TYPO3 Community, so if you find something wrong at your TYPO3 extension, then they can report.

Simply you can use your Git repository’s “Issues Management”, And make sure to provide “Link to issue tracker” at your extension as below.

How to Publish Your TYPO3 Extension to TER?

1. Manually Publish at Extensions.TYPO3.org

Step 1. Go to “My Extensions” at https://extensions.typo3.org/my-extensions/

Step 2. Click on “Upload” button at your registered TYPO3 extension

Step 3. Write a description, Upload yourextesion_1.0.0.zip, and Click on the “Upload extension” button.

2. Github: NamelessCoder’s Automatic Release

NamelessCoder.net mini-site is a service that lets you release a GitHub repository containing a TYPO3 extension directly from GitHub to the TYPO3 Extension Repository (TER). New releases are made every time a new version is tagged on GitHub. Free to use.

Requirements

  • A public GitHub repository containing your TYPO3 extension.

Installation

  • Go to Github Repository > Settings
  • Locate the "Webhooks & Services" tab
  • Click "Add webhook."
  • Enter in "URL": release.namelesscoder.net/my_extension.
  • my_extension is the lowercase underscored extension key to release.
  • Username: password is your credentials with permission to upload the extension.
  • Enter in "Secret": typo3rocks
  • Leave the "Events" selection as it is - this service only requires the push event.

Automatically Release Extension from Github to TER

create/push tag 
git tag 1.2.3 
git push origin 1.2.3

3. Gitlab: CI to TER

If you are using Gitlab, then you can simply write a deployment script into GitLab-ci.yml to automatically release the TYPO3 extension from Gitlab to TER.

# gitlab-ci.yaml

cache:
  key: "$CI_COMMIT_REF_NAME-$CI_JOB_STAGE"
  paths:
    - .composer/

before_script:
  - apk add git --update

stages:
  - upload

# TER Upload when tagging in the master branch
# The variables T3O_USERNAME and T3O_PASSWORD should be set in GitLab
ter-upload:
  image: php:7-alpine
  stage: upload
  only:
    - tags
  before_script:
    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
    - export COMPOSER_CACHE_DIR=.composer
  script:
    - composer install
    - composer require namelesscoder/typo3-repository-client
    - export TYPO3_PATH_WEB="$PWD/.Build/Web"
    - >
      if [ -n "$CI_COMMIT_TAG" ] && [ -n "$T3O_USERNAME" ] && [ -n "$T3O_PASSWORD" ]; 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"
        .Build/bin/upload . "$T3O_USERNAME" "$T3O_PASSWORD" "$TAG_MESSAGE"
      fi;

4. Github: TYPO3 Extension Utils (T3XUtils)

Important notes from author: Thanks for mentioning, But I do NOT recommend using T3XUtils anymore. It is not maintained for a while now. :-) https://twitter.com/etobi/status/1296809514839285761

Using Typo3ExtensionUtils tool, You can quickly deploy TYPO3 extension to TER using t3xutils.phar CLI. This is a collection of CLI utilities for the TYPO3 CMS Extension. The goal is to be able to do common tasks while developing extensions from the CLI. All tools work without a fully functional TYPO3 installation. Actually the TYPO3 CMS core isn't needed at all for these utilities.

Installation

git clone https://github.com/etobi/Typo3ExtensionUtils.git
cd Typo3ExtensionUtils/bin/
chmod +x t3xutils.phar
./t3xutils.phar help

Upload Extension to TER

./t3xutils.phar upload <typo3.org-username> <typo3.org-password> <extensionKey> "<uploadComment>" <pathToExtension>

./t3xutils.phar upload eTobi.de 'mySecretPassword' foobar "Minor Bugfixes and cleanup" /var/www/foobar/typo3conf/ext/foobar/

5. Github: Travis-CI to TER

Helmut - The TYPO3 man wrote an article to release TYPO3 Extension with Travis-CI to TER automatically.

# .travis.yml

language: php

# Do not build feature branches
branches:
  only:
    - latest
    - develop
    - /^v?([0-9]+\.){1,2}(x|[0-9]+)-?[a-z]*[1-9]*$/

# This is executed for all stages
before_install:
  - if php -i | grep -v TRAVIS_CMD | grep -q xdebug; then phpenv config-rm xdebug.ini; fi

# Configure build stages (with build matrix above, the test stage is implicitly defined)
jobs:
  allow_failures:
    - env: TYPO3_VERSION="dev-master"
  include:
    - stage: update extension repo
      if: type = push
      php: 7.2
      before_install: skip
      install: skip
      before_script:
        - mkdir -p ~/.ssh
        - openssl aes-256-cbc -K $encrypted_85bf36ae99bb_key -iv $encrypted_85bf36ae99bb_iv -in Resources/Private/deploy_rsa.enc -out ~/.ssh/id_rsa -d
        - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
        - chmod 600 ~/.ssh/id_rsa
        - git clone [email protected]:TYPO3-Console/Extension.git ../extension -b template
        - cd ../extension && git checkout origin/$TRAVIS_BRANCH || true && cd -
        - composer extension-release
        - cd ../extension
        - git checkout README.md
        - git add .
      script:
        - |
          if [ -n "$TRAVIS_TAG" ]; then
              git commit -m "Release extension version $TRAVIS_TAG" --author "Name <email>"
              git tag $TRAVIS_TAG
              git push --tags
            else
              git commit -m "Update extension based on commit $TRAVIS_COMMIT" --author "Name <email>"
              git push origin HEAD:$TRAVIS_BRANCH
          fi;
    - stage: ship to TER
      if: tag IS present
      php: 7.2
      install: skip
      before_script: skip
      script:
        - |
          if [[ "$TRAVIS_TAG" =~ ^v?([0-9]+\.)([0-9]+\.)([0-9]+)$ ]] && [ -n "$TYPO3_ORG_USERNAME" ] && [ -n "$TYPO3_ORG_PASSWORD" ]; then
            echo -e "Preparing upload of release ${TRAVIS_TAG} to TER\n";
            # Install ter client
            composer global require helhum/ter-client
            # Build extension files
            composer extension-release
            # Upload
            TAG_MESSAGE=`git tag -n10 -l $TRAVIS_TAG | sed 's/^[v]*[0-9.]*[ ]*//g'`
            echo "Uploading release ${TRAVIS_TAG} to TER"
            $HOME/.composer/vendor/bin/ter-client upload typo3_console ../extension -u "$TYPO3_ORG_USERNAME" -p "$TYPO3_ORG_PASSWORD" -m "$TAG_MESSAGE"
          fi;

6. TYPO3 Repository Client API/CLI

TYPO3 Extension Repository (TER) client library and CLI commands

Usage

Each command which can be executed has a corresponding class, for example, NamelessCoder\TYPO3RepositoryClient\Uploader and a CLI script which acts as a wrapper for said class. The parameters which should be passed to each CLI script must be the same arguments and in the same order as required by the class' method.

Uploader

// As component:
$uploader = new \NamelessCoder\TYPO3RepositoryClient\Uploader();
$uploader->upload('/path/to/extension', 'myusername', 'mypassword', 'An optional comment');

// And as CLI command:
./bin/upload /path/to/extension myusername mypassword "An optional comment"

7. TER Client

TYPO3 Extension Repository (TER) client library and Symfony Console command. This has been built on the shoulders of namelesscoder/typo3-repository-client.

Installation

Use composer to install the TER Client: composer require helhum/ter-client

Usage

Each command which can be executed has a corresponding class, for example, Helhum\TerClient\Uploader and a CLI script which acts as a wrapper for said class. The parameters which should be passed to each CLI script must be the same arguments and in the same order as required by the class' method.

Uploader


// As component:
$uploadPacker = new ExtensionUploadPacker();
$connection = Connection::create($wsdUrl);
$result = $connection->upload(
    new UsernamePasswordCredentials($username, $password),
    $uploadPacker->pack($extensionKey, $directory, $comment)
);

// And as CLI command:

ter-client upload ext_key /path/to/extension -u myusername -p mypassword -m "Upload Comment"

8. TER TYPO3 Extensions WSDL Services

CI environments (like Jenkins or GitLab CI) can execute these commands, it ought not to be that difficult to publish an extension automatically. 

Interestingly, there lies a public SOAP interface for the TYPO3 Extension Repository. The entirety of the as of now referenced solutions utilize this API. 

You can discover it under the URL https://typo3.org/wsdl/tx_ter_wsdl.php

If you wish to dig up, you can utilize the product SmartUI by SmartBear (Link: https://www.soapui.org/).

Tips & Tricks for TER TYPO3 Extensions

Semantic Versioning 2.0.0

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backward-compatible manner
  • PATCH version when you make backward-compatible bug fixes
  • Read more at semver.org

Support Composer

As a modern TYPO3 Developer, You should provide composer support.

Now it is time to configure composer, Packagist.org provides straightforward configuration to connect between your Git repository and Composer. Of course, Packagist also supports other Git platforms like Gitlab ;)

Submit Git repo at Packagist

Step 1: Go to https://packagist.org/

Step 2: To sign-up, you may use either https://packagist.org/register/ or use “Login with Github” at https://packagist.org/login/ 

Step 3: Now, Let’s submit our package/extension, Click on “Submit” https://packagist.org/packages/submit

Step 4: Enter your Github repository URL, and click on the “Check” button. Verify it once and then submit your package.

If you are getting some errors, then cross-verify your composer.json at your Git repository.

Step 5: Now you will be redirected to your package landing page eg., https://packagist.org/packages/nitsan/ns-news-comments Here you can see, all the information is grabbing from your Github’s composer.json file.

How Packagist and Git will communicate?

Whenever you’ll make any change or release a new version at Github, how will they communicate to take the latest code to the composer? Perform the following steps.

Get API Token from Packagist

Step 1: Go to your profile https://packagist.org/profile/

Step 2: Click on “Show Token API” button

Step 3: Go to your Github repository > Settings > Webhooks > Click on Add webhook button

Step 4: Fill-up details

Enable Composer Command

If you are all set with the composer, then make sure to “Enable Composer” for your TYPO3 extension at TER as below.

Hurray!
Your TYPO3 Extension detail page got a composer command.

// Support TYPO3 Composer Command
composer req nitsan/ns_backup

Wrap-up!

Thanks for reading the article!

I hope you learn and enjoy publishing TER TYPO3 Extensions. Let's quickly recap.

  • Setup your account at TYPO3.org, And register your extension key at TER.
  • Prepare your local environment with your favorite Git tool.
  • As an add-on, Do your best to make better documentation for users and developers.
  • Choose your convenient way to publish your TER TYPO3 extension; My favorite is NamelessCoder's service which is just plug-n-play.

What’s your favorite way to publish the TER TYPO3 extension? Are you facing any issues to set up one of the above methods to launch your TER TYPO3 extension? I’ll be happy to answer any questions in the comment box below.

Have a Happy TYPO3 Contribution :)

Post Comment

Your email address will not be published. Required fields are marked *

×

Name is required!

Enter valid name

Valid email is required!

Enter valid email address

Comment is required!

Google Captcha Is Required!

Comments :

  • Nikita Hovratov October 9, 2020 At 3:33 pm
    Really nice article! Exactly what i needed, thank you.
  • Erik Vogel September 4, 2020 At 2:04 pm
    Thanks Sanjay! The blog is awesome and I appreciate you taking the time to detail all the TYPO3 extension upload tricks out so well.
  • Erik Vogel September 4, 2020 At 2:00 pm
    Thanks Sanjay. The TYPO3 extension upload blog is super awesome and I appreciate you taking the time to detail all this out so well. I bookmarked this page just in case I really need it one day.
How to Create TYPO3 Form - Tutorial & Add-on Extensions

How to Create TYPO3 Form - Tutorial & Add-on Extensions

No matter what's role as editor, integrator, or developer, The TYPO3 form extension is a common topic with simple to advanced…

What Is TYPO3 Extension? An Introduction Guide

What Is TYPO3 Extension? An Introduction Guide

TYPO3 is an Open-source CMS and is a free tool for creating websites that put you in control of the design, features, and content…

Enrich Your Website With Multipurpose TYPO3 Sliders

Enrich Your Website With Multipurpose TYPO3 Sliders

Setting up a slider image on your TYPO3 website can be your game changer. A slider to your website can improve User Experience to…

Stay up to date with our recent TYPO3 Blogs, news, & updates