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 special files within an extension that have a special meaning
by convention. If put at the according places, TYPO3 will find them and
use 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.
Nearly none of these are required, but for example you can not have a TYPO3
extension recognized by TYPO3 without the ext_emconf.php
file etc. You
can read more details like that in the table below.
In general, do not introduce your own files in the root directory of
extensions with the name prefix ext_
.
Filename | Description |
---|---|
ext_emconf.php |
Definition of extension properties. This is the only mandatory file in the extension. It describes the extension for the rest of TYPO3. Name, category, status etc. Used by the extension manager. The content of this file is described in more details below. Note that it is auto-written by extension manager when extensions are imported from the repository. Note If this file is not present, the extension manager will not find the extension. |
ext_localconf.php |
Addition to This file contains hook definitions and plugin configuration. It must not contain a PHP encoding declaration. All Pay attention to the rules for the contents of these files. For more details, see the section below. |
ext_tables.php |
Included if found. 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 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 TCA definition of new database tables must be done entirely
in Customizations of existing tables must be done entirely
in |
ext_tables.sql |
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 therefore important to check and update 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 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 TYPO3 parses |
ext_tables_static+adt.sql |
Static SQL tables and their data. If the extension requires static data you can dump it into a 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.sql
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
Warning Static data is not meant to be extended by other extensions. On
re-import all extended fields and data is lost due to |
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
|
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
|
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 |
Configuration/Backend/Routes.php and Configuration/Backend/AjaxRoutes.php |
Registry of backend routes. Extension 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. |
Resources/Public/Icons/Extension.svg |
Extension icon. If exists, this icon is displayed in the extension manager. Preferred is using an SVG file, Extension icon will look nicer when provided as vector graphics (SVG) rather than bitmaps (GIF or PNG). 18x16 GIF, PNG or SVG icon for the extension. |
class.ext_update.php |
Local Update tool class If this file is found it will install a new menu item, "UPDATE", in
the extension manager when looking at details for the extension. When this
menu item is selected the class inside of this file (named Also you must add the function "access()" and make it return a boolean value whether or not the menu item should be shown. This feature is meant to let you disable the update tool if you can somehow detect that it has already been run and doesn't need to run again. The point of this file is to give extension developers the possibility to provide an update tool if their extensions in newer versions require some updates to be done. |
Reserved folders¶
In the early days, every extension baked it 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 extensions has been established. If extension authors
stick to this, the system helps in various ways. For instance, if putting
PHP classes into the Classes/
folder and naming classes accordingly,
the system will be able to autoload these without further action from the
developer.
Extension kickstarters like the Extension Builder extension 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 an 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 like
TCA
andBackend
have special meaning and files in there are automatically included during 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, one file per database table, using the name of the table for the file, plus ".php".
- 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 your 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 subfolders
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/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.