Files and locations¶
Files¶
An extension consists of:
- A directory named by the extension key (which is a worldwide unique
identification string for the extension), usually located in
typo3conf/ext
for local extensions, ortypo3/sysext
for system extensions. - Standard files with reserved names for configuration related to TYPO3 (of which most are optional, see list below)
- Any number of additional files for the extension functionality itself.
Reserved file names¶
This lists files within an extension that have a specific meaning
by convention. TYPO3 will scan for reserved file names and
use the content for specific functionality. For example, if a svg logo of your extension
is placed at Resources/Public/Icons/Extension.svg
, the Extension Manager
will show that image.
Most of these files are not required, except of ext_emconf.php
in legacy installations not based on Composer
and composer.json
in Composer installations
installations.
Note
It is recommended to keep ext_emconf.php
and composer.json
in
any public extension that is published to TYPO3 Extension Repository (TER), and
to ensure optimal compatibility with Composer installations and legacy
installations.
Do not introduce your own files in the root directory of
extensions with the name prefix ext_
, because that is reserved.
composer.json
¶
– required in Composer installations
For more information, see composer.json.
Changed in version 11.4: The ordering of installed extensions and their dependencies are loaded from
the composer.json
file, instead of ext_emconf.php
in
Composer installations.
Note
Extension authors should ensure that the information in the composer.json
file is in sync with the one in the extensions’ ext_emconf.php
file.
This is especially important regarding constraints like depends
, conflicts
and suggests
. Use the equivalent settings in composer.json
require
,
conflict
and suggest
to set dependencies and ensure a specific loading order.
ext_emconf.php
¶
– required in legacy installations
Definition of extension properties.
Name, category, status etc. are used by the Extensions module in legacy installations. The content of this file is described in more details in Declaration file (ext_emconf.php).
For legacy installations the ext_emconf.php
file is the
source of truth for required dependencies and the loading order of active
extensions.
ext_localconf.php
¶
– optional
Addition to LocalConfiguration.php
.
It should contain additional configuration of $GLOBALS['TYPO3_CONF_VARS']
.
This file contains hook definitions and plugin configuration. It must not contain a PHP encoding declaration.
All ext_localconf.php
files of loaded extensions are
included right after the files typo3conf/LocalConfiguration.php
and typo3conf/AdditionalConfiguration.php
during TYPO3
bootstrap.
Pay attention to the rules for the contents of these files. For more details, see the section below.
ext_tables.php
¶
– optional
Contains extensions of existing tables,
declaration of backend modules, etc. All code in such files
is included after all the default definitions provided by the Core and
loaded after ext_localconf.php
files during TYPO3
bootstrap.
Pay attention to the rules for the contents of these files. For more details, see the section below.
Note
In old TYPO3 Core versions, this file contained additions to the
global $GLOBALS['TCA']
array. This changed since Core version 6.2
to allow effective caching:
TCA definition of new database tables must be done entirely
in Configuration/TCA/<table name>.php
.
These files are expected to contain the full TCA of the given table
(as an array) and simply return it (with a return
statement).
Customizations of existing tables must be done entirely
in Configuration/TCA/Overrides/<table name>.php
.
ext_tables.sql
¶
– optional
SQL definition of database tables.
This file should contain a table-structure dump of the tables used by the extension. It is used for evaluation of the database structure and is applied to the database when an extension is enabled.
If you add additional fields (or depend on certain fields) to existing tables
you can also put them here. In that case insert a CREATE TABLE
structure
for that table, but remove all lines except the ones defining the fields you need,
here is an example adding a column to the pages table:
CREATE TABLE pages (
tx_myext_field int(11) DEFAULT '0' NOT NULL,
);
TYPO3 will merge this table definition to the existing table definition when comparing expected and actual table definitions. Partial definitions can also contain indexes and other directives. They can also change existing table fields though that is not recommended, because it may create problems with the TYPO3 Core and/or other extensions.
The ext_tables.sql
file may not necessarily be “dumpable”
directly to MySQL (because of the semi-complete table definitions allowed
defining only required fields). But the Extension Manager or Install Tool can handle this.
TYPO3 parses ext_tables.sql
files. TYPO3 expects that all
table definitions in this file look like the ones produced by the
mysqldump
utility. Incorrect definitions may not be recognized
by the TYPO3 SQL parser or may lead to MySQL errors, when TYPO3 tries
to apply them. If TYPO3 is not running on MySQL or directly compatible
other DBMS like MariaDB, the system will parse the file towards the
target DBMS like PostgreSQL.
Auto generated structure¶
The database schema analyzer automatically creates TYPO3 “management” related
database columns by reading a tables TCA and checking the Table properties (ctrl)
section for table capabilities. Field definitions in ext_tables.sql
take
precedence over automatically generated fields, so the Core never overrides a
manually specified column definition from an ext_tables.sql
file.
These columns below are automatically added if not defined in
ext_tables.sql
for database tables that provide a $GLOBALS['TCA']
definition:
uid
andPRIMARY KEY
- If uid field is not provided inside
ext_tables.sql
, thePRIMARY KEY
must be omitted, too. pid
andKEY parent
- Column pid is
unsigned
if the table is not workspace aware, the default indexparent
includespid
andhidden
as well asdeleted
if the latter two are specified inTCA
Table properties (ctrl). The parent index creation is only applied if columnpid
is auto generated, too. ['ctrl']['tstamp'] = 'fieldName'
- Often set to
tstamp
orupdatedon
['ctrl']['crdate'] = 'fieldName'
- Often set to
crdate
orcreatedon
['ctrl']['cruser_id'] = 'fieldName'
- Often set to
cruser
orcreatedby
['ctrl']['delete'] = 'fieldName'
- Often set to
deleted
['ctrl']['enablecolumns']['disabled'] = 'fieldName'
- Often set to
hidden
ordisabled
['ctrl']['enablecolumns']['starttime'] = 'fieldName'
- Often set to
starttime
['ctrl']['enablecolumns']['endtime'] = 'fieldName'
- Often set to
endtime
['ctrl']['enablecolumns']['fe_group'] = 'fieldName'
- Often set to
fe_group
['ctrl']['sortby'] = 'fieldName'
- Often set to
sorting
['ctrl']['descriptionColumn'] = 'fieldName'
- Often set to
description
['ctrl']['editlock'] = 'fieldName'
- Often set to
editlock
['ctrl']['languageField'] = 'fieldName'
- Often set to
sys_language_uid
['ctrl']['transOrigPointerField'] = 'fieldName'
- Often set to
l10n_parent
['ctrl']['translationSource'] = 'fieldName'
- Often set to
l10n_source
l10n_state
- Column added if
languageField
andtransOrigPointerField
are set ['ctrl']['origUid'] = 'fieldName'
- Often set to
t3_origuid
['ctrl']['transOrigDiffSourceField'] = 'fieldName'
- Often set to
l10n_diffsource
['ctrl']['versioningWS'] = true
-t3ver_*
columns- Columns that make a table workspace aware. All those fields are prefixed with
t3ver_
, for examplet3ver_oid
. A default index namedt3ver_oid
to fieldst3ver_oid
andt3ver_wsid
is added, too.
ext_tables_static+adt.sql
¶
Static SQL tables and their data.
If the extension requires static data you can dump it into an SQL file by this name. Example for dumping mysql data from bash (being in the extension directory):
mysqldump --add-drop-table \
--password=[password] [database name] \
[tablename] > ./ext_tables_static+adt.sql
--add-drop-table
will make sure to include a DROP TABLE
statement so any data is inserted in a fresh table.
You can also drop the table content using the Extension Manager in the backend.
Note
The table structure of static tables needs to be in the
ext_tables.sql
file as well - otherwise an installed static
table will be reported as being in excess in the Install Tool.
Warning
Static data is not meant to be extended by other extensions. On
re-import all extended fields and data is lost due to DROP TABLE
statements.
ext_typoscript_constants.typoscript
¶
Preset TypoScript constants. Will be included in the constants section of all TypoScript templates.
Warning
Use such a file if you absolutely need to load some TS (because you
would get serious errors without it). Otherwise static templates or
usage of the Extension Management API of class
TYPO3\CMS\Core\Utility\ExtensionManagementUtility
are preferred.
ext_typoscript_setup.typoscript
¶
Preset TypoScript setup. Will be included in the setup section of all TypoScript templates.
Warning
Use such a file if you absolutely need to load some TS (because you
would get serious errors without it). Otherwise static templates or
usage of the Extension Management API of class
TYPO3\CMS\Core\Utility\ExtensionManagementUtility
are preferred.
ext_conf_template.txt
¶
Extension Configuration template.
Configuration code in TypoScript syntax setting up a series of values which can be configured for the extension in the Install Tool. Read more about the file format here.
If this file is present ‘Settings’ of the Install Tool provides you with an
interface for editing the configuration values defined in the file. The result is
written as an array to LocalConfiguration.php
in the variable $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS'][
*extension_key*
]
RequestMiddlewares.php
¶
Full path to this file is: Configuration/RequestMiddlewares.php
.
Configuration of user-defined middlewares for frontend and backend. Extensions that add middlewares or disable existing middlewares configure them in this file. The file must return an array with the configuration. For more details, see Configuring middlewares.
Routes.php
and AjaxRoutes.php
¶
Full paths to these files are: Configuration/Backend/Routes.php
and
Configuration/Backend/AjaxRoutes.php
.
Registry of backend routes. Extensions that add backend modules must
register their routes here to be correctly linkable in the backend.
The file must return an array with routing details. See Core extensions
like backend
for examples.
Configuration/Services.yaml
¶
Services can be configured in this file. TYPO3 uses it for:
- Dependency Injection
- Event Listeners
- Command Controllers (see Feature: #89139 - Add dependency injection support for console commands)
- Registering a widget with the dashboard
See ServicesYaml for details.
Resources/Public/Icons/Extension.svg
¶
Alternatives: Resources/Public/Icons/Extension.png
, Resources/Public/Icons/Extension.gif
SVG, PNG or 18x16 GIF extension icon
If it exists, this icon is displayed in the Extension Manager. Preferred is using a SVG file, because the extension icon will look nicer as a vector graphic (SVG) rather than a bitmap (PNG or GIF).
Reserved Folders¶
In the early days, every extension author baked his own bread when it came to file locations of PHP classes, public web resources and templates.
With the rise of Extbase, a generally accepted structure for file
locations inside of extensions has been established. If extension authors
stick to this and the other Coding Guidelines, the system helps in various ways. For instance, if putting
PHP classes into the Classes/
folder and using appropriate namespaces for the classes,
the system will be able to autoload these files.
Extension kickstarters like the Extension Builder will create the correct structure for you.
It is described below:
- Classes
- Contains all PHP classes. One class per file. Should have sub folders like
Controller/
,Domain/
,Service/
orView/
. For more details on class file namings and PHP namespaces, see chapter namespaces.
- Classes/Controller
- Contains MVC Controller classes.
- Classes/Domain/Model
- Contains MVC Domain model classes.
- Classes/Domain/Repository
- Contains data repository classes.
- Classes/ViewHelpers
- Helper classes used in (Fluid) views.
- Configuration
- General configuration folder. Some of the sub directories in here have reserved names with special meanings.
All files in this directory and in the 2 sub directories
TCA
andBackend
are automatically included during the TYPO3 bootstrap.
- Configuration/Backend/
- Contains backend routing configurations. See files description of
Routes.php
andAjaxRoutes.php
above.
- Configuration/TCA
- One file per database table, using the name of the table for the file, plus “.php”. Only for new tables.
- Configuration/TCA/Overrides
- For extending existing tables. General advice: One file per database table, using the name of the table for the file, plus “.php”. For more informations, see chapter Extending the TCA Array.
- Configuration/TSconfig/Page
- page TSconfig, see chapter ‘page TSconfig’ in the TSconfig Reference. Files should have the file extension
.tsconfig
.
- Configuration/TSconfig/User
- User TSconfig, see chapter ‘user TSconfig’ in the TSconfig Reference. Files should have the file extension
.tsconfig
.
- Configuration/TypoScript
- TypoScript static setup (
setup.typoscript
) and constants (constants.typoscript
). Use subfolders if you have several static templates.
- Documentation
- Contains the extension documentation in ReStructuredText (ReST, .rst) format.
Read more on the topic in chapter extension documentation.
Documentation/
and its subfolders may contain several ReST files, images and other resources.
- Documentation/Index.rst
- This file contains the cover page of the extension manual in ReST format. The name or format of the file may not be changed. You may include other ReST files as you like. See the “Extension Template” on docs.typo3.org for more information about structure and syntax of extension manuals.
- Resources
- Contains the sub folders
Public/
andPrivate/
, which contain resources, possibly in further subfolders, e.g.Templates/
,Css/
,Language/
,Images/
orJavaScript/
. This is also the directory for non–TYPO3 files supplied with the extension. TYPO3 is licensed under GPL version 2 or any later version. Any non–TYPO3 code must be compatible with GPL version 2 or any later version.
- Resources/Private/Language
- XLIFF files for localized labels.
- Resources/Private/Layouts
- Main layouts for (Fluid) views.
- Resources/Private/Partials
- Partial templates for repetitive use.
- Resources/Private/Templates
- One template per action, stored in a folder named after each Controller.
- Resources/Public
Public assets used in extensions (files that should be delivered by the web server) must be located in the Resources/Public folder of the extension. This folder should only be used for static assets. If you need to create assets during runtime, they should be stored in
typo3temp/
.Deprecated since version 11.5: Having public assets in any but the folder Resources/Public has been deprecated with version 11.5.
- Resources/Public/Css
- Any CSS file used by the extension.
- Resources/Public/Images
- Any images used by the extension.
- Resources/Public/JavaScript
- Any JS file used by the extension.
- Tests/Unit
- Contains unit tests and fixtures.
- Tests/Functional
- Contains functional tests and fixtures.