Attention

TYPO3 v8 has reached its end-of-life March 31st, 2020 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.

There is no further ELTS support. It is recommended that you upgrade your project and use a supported version of TYPO3.

Creating a new distribution

This chapter describes the main steps in creating a new distribution. It should not be considered as a full fledge tutorial.

Concept of distributions

Distributions are full TYPO3 CMS websites ready to be unpacked. They provide an easy quickstart for using TYPO3 CMS.

A distribution takes care of the following parts:

  • Deliver initial database data

  • Deliver fileadmin files

  • Deliver configuration for a package

  • Hook into the process after saving configuration to trigger actions dependent on configuration values

  • Deliver dependent extensions (e.g., customized versions or extensions not available through TER)

Kickstarting the distribution

A distribution is a special kind of extension. The first step is thus to create a new extension. Start by registering an extension key, which will be the unique identifier of your distribution.

Next create the Extension declaration file as usual, except for the "category" property which must be set to distribution.

Configuring the distribution display in the EM

You should provide two preview images for your distribution. Provide a small 220x150 pixels for the list in the extension manager as Resources/Public/Images/Distribution.png and a larger 300x400 pixels welcome image as Resources/Public/Images/DistributionWelcome.png. The welcome image is displayed in the distribution detail view inside the extension manager.

Fileadmin files

Create the following folder structure inside your extension:

  • Initialisation

  • Initialisation/Files

All the files inside that second folder will be copied to fileadmin/<extkey> during installation, where "extkey" is the extension key of your distribution.

Database data

The database data is delivered as TYPO3 CMS export data.t3d. Generate this file by exporting your whole installation from the tree root with the import/export module. Make sure to include all tables in the export.

The file has to be name data.t3d and must be located in the Initialisation folder.

Distribution configuration

A distribution is technically handled as an extension. Therefore your can make use of all configuration options as needed.

After saving the configuration, the signal afterExtensionConfigurationWrite is dispatched. You may use this to alter your website configuration (e.g. color scheme) on the fly.

Delivering custom dependencies

Normally extension dependencies are setup in the Extension declaration file.

However sometimes, extensions are not available in the TYPO3 Extension Repository (TER). Therefore, a distribution can act as its own extension repository. Add unpacked extensions to Initialisation/Extensions/ to provide dependencies. Your main extension has to be dependent on these extension as normal dependencies in ext_emconf.php.

Extensions delivered inside an extension have the highest priority when extensions need to be fetched.

Caution

This will not overwrite extensions already present in the system.

Test your distribution

To test your distribution, simply copy your extension to an empty TYPO3 CMS installation and try to install it from the Extension Manager.

Warning

It is not enough to clean all files and the page tree if you want to try again to install your distribution. Indeed, TYPO3 CMS remembers that it previously imported your distribution and will skip any known files. Make sure to clean the table "sys_registry" if you want to work around that.