typo3 / tailor

CLI Tool for maintaining public TYPO3 Extensions

TYPO3 CMS

TYPO3 is an open source PHP based web content management system released under the GNU GPL. TYPO3 is copyright © 1999-2024 by Kasper Skårhøj.

This document provides a basic introduction to TYPO3.

Getting Started

TYPO3 requires a web server with PHP and a database. The backend is accessed via a supported browser.

Please see the Installation Guide in order to set up a basic TYPO3 installation on your web server.

What is TYPO3?

TYPO3 is a free and open source Content Management Framework. It is released under the GNU General Public License. It can run on several web servers, such as Apache, nginx or IIS, on top of many operating systems, among them Linux, Microsoft Windows, FreeBSD or macOS.

TYPO3 was initially authored by Kasper Skårhøj and is now further developed by a community of contributors and the TYPO3 Core Development Team.

To get more info about the GPL license, visit https://opensource.org/licenses/gpl-license

What is a Content Management Framework?

A Content Management Framework is more than just a content management system, due to the separation of the streamlined core and optional plugins (extensions). TYPO3 has an open API that allows you to extend the frontend (website) and/or backend (administration) functionality.

The concept of extensions makes TYPO3 capable of being developed and used in almost any way you can imagine, either by using any of the many extensions which are available for download, or by writing your own.

TYPO3 System requirements

TYPO3 is based upon PHP and uses a database management system like MySQL.

For more specific information regarding requirements see the file INSTALL.md in this folder.

TYPO3 resources

Here is an overview of the most important TYPO3 resources to help you get started:

Get more information

• https://typo3.org/ is the main project website. It provides up-to-date official news, information about events and the TYPO3 community.

• https://docs.typo3.org/: TYPO3 is one of the most thoroughly documented OpenSource products around, with manuals covering basic tutorials, TypoScript, administration, development, core structure, etc. You should make the time to locate the various documents, and read those that apply to the work you want to do.

• https://get.typo3.org/ is the platform where you can download TYPO3 and find all release notes and change logs of TYPO3 releases.

• https://extensions.typo3.org/ is the platform where you can search for and download TYPO3 extensions.

Chat with us

The TYPO3 community is using a tool called Slack to openly communicate with each other and with the public. Several TYPO3 teams use Slack as a way to communicate internally and most channels are a welcome place for you to join and get yourself involved.

• Register: https://my.typo3.org/about-mytypo3org/slack
• Slack: https://typo3.slack.com/

Exchange information, ask questions, get help

Slack is nice for short discussions, but when asking questions, most answers are lost in the noise after a few minutes.

StackOverflow

To let everyone profit from an answer, we recommend to ask questions on StackOverflow. If you like, you can then post a link into the corresponding Slack channel to raise attention. And please, do not forget to tag your questions correctly with typo3 (and possibly other tags like typo3-9.5.x, Fluid or Extbase).

• StackOverflow questions tagged "TYPO3"

Official meet the TYPO3 Community overview:

Visit https://typo3.org/community/meet/

Contributing

If you want to contribute to the TYPO3 source code, take a look at our Contributors Walkthrough and Review System:

• https://docs.typo3.org/core-contribution
• https://review.typo3.org/

Please use the TYPO3 Slack chat, if you need help in setting up your contribution environment. The community is very helpful and get you up and running! (Please post your questions in Slack Channel #typo3-cms-coredev regarding contribution support)

The repository at GitHub is a synchronized mirror of the primary TYPO3 core git repository:

• https://git.typo3.org/typo3/typo3

If you want to file a bug report, take a look at:

• https://forge.typo3.org

Security

If you learn about a potential security issue in the TYPO3 core or in an extension, please always contact the TYPO3 Security Team via [email protected]. Please always include the version number where you've discovered the issue. If we can confirm a problem in a third-party extension, we will inform the author immediately.

If you discover a security problem in your own extension, please inform the TYPO3 Security Team as well. They can help you to fix it, and they may want to issue an advisory once it is fixed.

For more details see TYPO3 Security Team.

Final notes

TYPO3 is said to be one of the most sophisticated PHP / Internet related applications available, and the more you play with it, the more you will agree.

Due to the advanced level of the code and functionality, a degree of study, time and perseverance is required to fully understand it, and get the best from it. You should keep trying, as we say it's definitely worth it. TYPO3 is the Enterprise Content Management System "for all".

The GPL license allows for developments that are based upon TYPO3 to also be freely available under the GPL. Please remember this, because TYPO3 is about "Inspiring People To Share". If you are making money with TYPO3 you can donate or become a member of the TYPO3 Association.

By becoming a supporting member, individuals and organisations mainly fund core development of TYPO3. The decision about what the funds are used for, is made by all members of the Association and the TYPO3 Association Board. The decisions will be made transparent to the community and especially the supporting members. Your funds will also serve for other purposes as laid out in the bylaws.

• Donate to TYPO3
• Become a member of the TYPO3 Association

Copyleft

This document is a part of the TYPO3 project.

tailor's Issues

[BUG] Upload not possible: no or no valid ext_conf.php

Summary / Description

When I try to upload an extension using tailor I get "No or invalid ext_emconf.php found in the folder."

Version

tailor 1.1.1

Steps to reproduce

Command:

vendor/typo3/tailor/bin/tailor ter:publish 2.0.6 poll --artefact=/my/path/poll.zip

Extension is attached

Expected behaviour

The extension is published to TER.

Actual behavior

The error message "No or invalid ext_emconf.php found in the folder." appears.

Additional

After unpacking and packing the zip archive the upload works.

Uploading via GUI and t3xutils is possible.

Extension file

poll.zip

[FEATURE] Make it compatible with Symfony 7 (and TYPO3 13)

Summary / Description

Make it compatible with Symfony 7 (and TYPO3 13) so I can release my extension for TYPO3 13.0 ;)

[FEATURE] Add repository to "Pinned repositories"

This app is probably one of the most important to facilitate contribution to the TYPO3 ecosystem, so I would pin it prominently to the top of the profile page.

[FEATURE] Read extension key from composer.json

set-version no-docs option looks wrong

The input type of the no-docs option should imho be NO_VALUE see

tailor/src/Command/Extension/SetExtensionVersionCommand.php

Line 42 in 2b4fa52

->addOption('no-docs', '', InputOption::VALUE_OPTIONAL, 'Disable version update in documentation settings', false);

[BUG] extension code was published in wrong extension

Summary / Description

cs_seo version 6.6.0 was now released as go_maps_ext

In detail:
https://extensions.typo3.org/extension/go_maps_ext has now a release 6.6.0 of cs_seo https://extensions.typo3.org/extension/cs_seo

Version

Version in which the bug occurs.

Steps to reproduce

I have to two extenions in my local project. I changed the .env variables from one extension to another. Than I wanted to publish the extension via tailor ter:publish cs_seo. It happend that my extension was published as the other extension, which was set in the .env before.

Expected behaviour

How can I prevent this in the future?

[FEATURE] Mention GitHub action `typo3-upload-ter` of Tomas Norre

The README.md documentation could include a comment and link to Tomas Norre's GitHub action https://github.com/tomasnorre/typo3-upload-ter in the "Github Actions Workflow" chapter, which further facilitates the configuration of the GitHub workflow so that the user is left with

• creating an extension access token
• creating a GitHub secret with the fixed name TYPO3_API_TOKEN with this access token.
• adding almost a one liner to the GitHub workflow
• adding a commit with a tag, pushing it and watching the GitHub action.

Amazingly simple and already available in TYPO3 documentation repositories like

• TYPO3-Documentation/tea
• TYPO3-Documentation/t3docs-examples

[FEATURE] --dry-run option

Summary / Description

A --dry-run option would be a cool thing for debugging.

[FEATURE] I want to be able to tag my version with a v-prefix

Summary / Description

I'm tagging my extensions with v1.0.0 with a v-prefix. I'm not sure if I should strip the v before or if the release command should internally remove it.

Describe the solution you'd like

Remove the v-prefix either in the CI with some bash commands or internally.

Command tests are missing

At the moment the commands and its parameters are not tested. To avoid regressions for the user, tests should be added properly.

I will take care once my pending PRs are merged.

[BUG] vendors.phar file not uploaded

Summary / Description

When there is a vendors.phar file in the current directory, this file is not uploaded to the TER.

Version

1.4.0

Steps to reproduce

1. Generate a vendors.phar, e.g. using clue/phar-composer, but even a simple touch vendors.phar will do.
2. Run tailor ter:publish ... in the current directory.
3. Check the published release in the TER

Expected behaviour

The TER release archive should contain the vendors.phar.

Actual behavior

There is no vendors.phar in the TER release archive.

Example: https://extensions.typo3.org/extension/formlog#v2.1.1

Additional

Possible fix

Adjust the directories filtering here to make sure there's a trailing / in the path and pattern:

tailor/src/Service/VersionService.php

Line 86 in 0362f48

if (preg_match('/^' . $excludeDirectory . '/i', $path)) {

Miscellaneous

Currently the vendor entry within directories here very likely causes the vendors.phar file to be skipped:

tailor/conf/ExcludeFromPackaging.php

Line 26 in 0362f48

'vendor',

[BUG] Documentation has not been rendered since 2021

There is rendered Documentation of this Repository at https://docs.typo3.org/other/typo3/tailor/main/en-us/ which has not been rerenderered since 2021. Should we delete it from intercept or would you like to create a github action triggering re-rendering?

Set version for Documentation

A good extension is even better if it features a documentation in ReST within Documentation/.

It would be cool that set-version would update the version there as well (file Documentation/Settings.cfg).

More information: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/GeneralConventions/DirectoryFilenames.html#settings-cfg

tl;dr

This is an INI-like file structure and you need to update both version and release within section [general]:

[general]
project     = File List
version     = 2.5
release     = 2.5.0
t3author    = Xavier Perseguers
copyright   = 2008-2020
description = This extension provides a frontend plugin which
      shows a list of files and folders in a specified directory
      on the file system (comparable to Apache directory listing)
      or using more advanced FAL selectors (categories, collection
      of files, ...). This extension may also be used for creating
      image galleries. Default templates are Bootstrap-ready.

Usage of ter:token:refresh is not clear

I've tried to write a GH workflow to periodically refresh the access token and update the secrets. Currently it looks like user name and password are required for this action, I'm currently getting the error No authentication credentials are defined.

Wondering why I have to provide the credentials at all, thought for this reason the refresh token is provided. Saving the credentials at GH is a no go for some people.

[FEATURE] Add helpful error messages

Summary / Description

Currently, my TER release is failing with the following message:
No or invalid ext_emconf.php found in the folder.

I'd like to have specific error messages like this so I know what the problem is:

• file ext_emconf.php missing
• $EM_CONF not set
• $EM_CONF is no array
• version info missing in $EM_CONF
• typo3 dependency missing in $EM_CONF
• version number 1.2.3 in $EM_CONF is different than the version number 1.2.4 provided as an argument

[BUG] Does not work with TYPO3 9 composer

Summary / Description

It's not possible to add tailor via composer to a TYPO3 9 installation because of the dependencies of symfony/console.

Seen in use at https://github.com/b13/menus/blob/master/composer.json#L16

Version

All

Steps to reproduce

Have a TYPO3 9 installation based on composer and execute:

composer req typo3/tailor --dev

Expected behaviour

It can be installed

Actual behavior

typo3/tailor 1.1.0 requires symfony/console ^5.1 -> found symfony/console[v5.1.0, ..., v5.2.0] but the package is fixed to v4.4.17 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.

[BUG] Wrong exit code after successful extension publish

I wrote a GitLab CI configuration to upload my extension to TER via tailor.
It suceeds with upload but my job was marked as failed, see: https://git.spooner.io/spooner-web/tcabuilder/-/jobs/7249.

It should exit with the correct exit code "0".

[FEATURE] Have ExcludeFromPackaging respect .gitattributes file

Summary / Description

Talking with @georgringer this morning as he asked about if my GitHub Action respects the .gitattributes-file. I look into the Tailor and say it's a manually maintain list (1) of files that would be included.

I find that perfectly OK, but would suggest having the .gitattributes respected as well.

Describe alternatives you've considered

Haven't considered other alternative yet.

Possible solution

My suggestion would be to parse the .gitattributes file and added to the array of /conf/ExcludeFromPackaging.php

Links

[1] https://github.com/TYPO3/tailor/blob/main/conf/ExcludeFromPackaging.php

[BUG] github action example: set-output deprecated

Summary / Description

When using actions/checkout@v3 (v2 is deprecated), this warning is shown:

The set-output command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more information see: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/

I guess at least the example in README.md should be adapted somehow.

[BUG] Transfer-Encoding missing

The Transfer-Encoding header is currently missing for POST request which leads to a negative score on the server side. It should be submitted properly where needed to avoid further issues.

[BUG] Run tests with PHP 8.1

Please go ahead and add PHP 8.1 testing to github actions.