From aa466f5a85cfd890fb936c4737b1b94f7c27caeb Mon Sep 17 00:00:00 2001 From: Sarah McCarthy Date: Wed, 19 Nov 2025 14:20:21 +0100 Subject: [PATCH] [TASK] Overhaul extension development concepts Releases: main, 13.4 --- .../FileStructure/Classes/Index.rst | 4 +- .../Configuration/Backend/Index.rst | 16 +++---- .../Extbase/Persistence/Index.rst | 6 +-- .../FileStructure/Configuration/Icons.rst | 2 +- .../FileStructure/Configuration/Index.rst | 11 ++--- .../Configuration/PageTsconfig.rst | 4 +- .../Configuration/ServicesYaml.rst | 4 +- .../Configuration/Sets/Index.rst | 31 ++++++------ .../FileStructure/Configuration/TCA/Index.rst | 10 ++-- .../Configuration/TsConfig/Index.rst | 4 +- .../Configuration/TypoScript/Index.rst | 24 +++++----- .../Configuration/UserTsconfig.rst | 8 ++-- .../FileStructure/Index.rst | 48 +++++++++---------- 13 files changed, 83 insertions(+), 89 deletions(-) diff --git a/Documentation/ExtensionArchitecture/FileStructure/Classes/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Classes/Index.rst index 8074a9befc..0828887b2f 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Classes/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Classes/Index.rst @@ -8,9 +8,9 @@ Extension folder `Classes` for PHP classes ========================================== -Contains all PHP classes. One class per file. Should have sub folders like +Contains all the PHP classes in an extension, with one class per file. Should have subfolders like :code:`Controller/`, :code:`Domain/`, :code:`Service/` or :code:`View/`. -For more details on class file namings and PHP namespaces, see chapter +For more details on class file naming and PHP namespaces, see chapter :ref:`namespaces `. Typical PHP classes in this folder: diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst index 92274bef37..033ed64d24 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst @@ -11,10 +11,10 @@ Extension folder `Configuration/Backend` ======================================== -The folder :file:`EXT:my_extension/Configuration/Backend/` may contain -configuration that is important within the TYPO3 Backend. +The folder :file:`EXT:my_extension/Configuration/Backend/` contains +configuration that is important in the TYPO3 Backend. -All files in this directory are automatically included during the TYPO3 +All files in this directory are automatically included during TYPO3 bootstrap. .. _extension-configuration-backend-ajaxroutes: @@ -25,8 +25,7 @@ bootstrap. :regex: /^.*Configuration\/Backend\/AjaxRoutes\.php$/ :shortDescription: Defines routes for backend Ajax requests - In this file routes for Ajax requests that should be used in the backend can - be defined. + Defines file routes for Ajax requests in the backend. Read more about :ref:`Using Ajax in the backend `. @@ -40,10 +39,9 @@ bootstrap. :regex: /^.*Configuration\/Backend\/Routes\.php$/ :shortDescription: Defines routes for backend controllers - This file maps the URI paths used in the backend to the controller that should - be used. + This file maps URI paths in the backend to controllers. - Most backend routes defined in the TYPO3 core can be found in the following + Backend routes defined in the TYPO3 core are in the following file, which you can use as example: :t3src:`backend/Configuration/Backend/Routes.php` @@ -58,6 +56,6 @@ bootstrap. :regex: /^.*Configuration\/Backend\/Modules\.php$/ :shortDescription: Defines the backend module configuration - This file is used for the + This file is used for :ref:`Backend module configuration `. See that chapter for details. diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Extbase/Persistence/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Extbase/Persistence/Index.rst index fe5ab2a1ce..00cb99a72f 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Extbase/Persistence/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Extbase/Persistence/Index.rst @@ -6,7 +6,7 @@ :file:`Persistence` =================== -This folder can contain the following files: +This folder contains the following file: .. _extension-configuration-extbase-persistence-classes: @@ -16,8 +16,8 @@ This folder can contain the following files: :regex: /^.*Configuration\/Extbase\/Persistence\/Classes\.php$/ :shortDescription: Contains the mapping between a database table and its Extbase model - In the file :file:`EXT:my_extension/Configuration/Extbase/Persistence/Classes.php` the - mapping between a database table and its model can be configured. The mapping + :file:`EXT:my_extension/Configuration/Extbase/Persistence/Classes.php` is + used to configure mapping between a database table and its model. The mapping in this file overrides the automatic mapping by naming convention. .. seealso:: diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Icons.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Icons.rst index d3142b8262..cdf07bebe3 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Icons.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Icons.rst @@ -14,7 +14,7 @@ :regex: /^.*Configuration\/Icons\.php$/ :shortDescription: Registration of custom icons - In this file custom icons can be registered in the + This file registers custom icons to the :php:`\TYPO3\CMS\Core\Imaging\IconRegistry`. See the :ref:`Icon API ` for details. diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Index.rst index e3f6d64600..23dd3c86f1 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Index.rst @@ -11,16 +11,15 @@ Extension folder `Configuration` ================================ -The folder :file:`EXT:my_extension/Configuration/` may contain +The folder :file:`EXT:my_extension/Configuration/` contains configuration of different types. -Some of the sub directories in here have reserved names with special meanings. +Most subdirectories have reserved names. -All files in this directory and in the sub directories :file:`TCA` and -:file:`Backend` are automatically included during the TYPO3 bootstrap. +Files in the root of this directory and in the :file:`TCA` and +:file:`Backend` subdirectories are automatically included during TYPO3 bootstrap. -The following files and folders are commonly found in the :file:`Configuration` -folder: +The typical file structure is: .. directory-tree:: diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/PageTsconfig.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/PageTsconfig.rst index f4b7794ad7..8a10f207a6 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/PageTsconfig.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/PageTsconfig.rst @@ -12,7 +12,7 @@ Page TSconfig can be set using `the site as Page TSconfig provider `_ - Only put page TSconfig in this file which absolutely has to be set globally. + Only put global page TSconfig in this file. .. typo3:file:: page.tsconfig :scope: extension @@ -21,7 +21,7 @@ :shortDescription: Global page TSconfig In this file global page TSconfig can be stored. It will be automatically - included for all pages. + included in all pages. For details see :ref:`Setting the page TSconfig globally `. diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst index ab5116df65..f7d942edd4 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst @@ -9,7 +9,7 @@ `Services.yaml` =============== -It is possible to use a YAML or PHP format: +It is possible to use YAML or PHP format: .. typo3:file:: Services.yaml :scope: extension @@ -23,7 +23,7 @@ It is possible to use a YAML or PHP format: :regex: /^.*Configuration\/Services\.php$/ :shortDescription: Dependency injection service configuration -Services can be configured in this file. TYPO3 uses it for: +This file can configure services. TYPO3 uses it for: * :ref:`Dependency Injection ` * :ref:`Event Listeners ` diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Sets/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Sets/Index.rst index a59eaae37d..85ab76c11b 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/Sets/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/Sets/Index.rst @@ -11,11 +11,12 @@ Extension folder `Configuration/Sets` `Site sets `_ have been introduced. -In this directory TYPO3 extensions can provide their +This directory contains an extension's `Site sets `_. -Each set must be saved in its own directory and have at least a file called -:file:`config.yaml`. +Each set must be in its own directory and consist of at least a +:file:`config.yaml` file. + .. _extension-configuration-sets-config-yaml: @@ -25,8 +26,8 @@ Each set must be saved in its own directory and have at least a file called :regex: /^.*Configuration\/Sets\/[\w\-]+\/config\.yaml$/ :shortDescription: Contains the definition of a site set. Mandatory. - Contains the `definition of a site set `_ - and its dependencies. + Contains the `definition of the site set `_ + and any dependencies. Example: @@ -40,8 +41,8 @@ Example: :regex: /^.*Configuration\/Sets\/[\w\-]+\/settings\.yaml$/ :shortDescription: Override settings defined by other sets. - In this file an extension can override settings defined by other sets. For - example :ref:`Settings provided by site set "Fluid Styled Content" `: + In this file an extension can override settings defined by other sets, for + example, :ref:`settings defined in the "Fluid Styled Content" site set `: .. literalinclude:: /ApiOverview/SiteHandling/_Sets/_site-package/_settings-map.yaml :language: yaml @@ -66,12 +67,12 @@ Example: :regex: /^.*Configuration\/Sets\/[\w\-]+\/setup\.typoscript$/ :shortDescription: Provides frontend TypoScript for sites depending on this set. - This file contains the Frontend :ref:`TypoScript ` - that the set should provide. If the + This file contains a set's Frontend + :ref:`TypoScript `. If the extension keeps its TypoScript in folder `TypoScript `_ - for backward compatibility reasons this file **should** contain an import of - file :file:`Configuration/TypoScript/setup.typoscript` for the main set of the - extension: + for backward compatibility reasons, this file **should** import + the :file:`Configuration/TypoScript/setup.typoscript` file in the main + extension set: .. code-block:: typoscript :caption: EXT:my_extension/Configuration/Sets/MySet/setup.typoscript @@ -87,8 +88,8 @@ Example: :regex: /^.*Configuration\/Sets\/[\w\-]+\/constants\.typoscript$/ :shortDescription: Provides frontend TypoScript constants for sites depending on this set. - This file contains the Frontend TypoScript Constants that the set should - provide. This file can be used if your extension depends on other extensions + This file contains the Frontend TypoScript Constants in the set. + This file should be used if the extension depends on other extensions that still rely on TypoScript constants. .. _extension-configuration-sets-page-tsconfig: @@ -100,4 +101,4 @@ Example: :shortDescription: Provides page TSconfig (backend TypoScript) for sites depending on this set. This file contains the :ref:`Page TSconfig ` - (backend TypoScript) that the set should provide. + (backend TypoScript). diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/TCA/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/TCA/Index.rst index 243c387fdc..406b8f1f8d 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/TCA/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/TCA/Index.rst @@ -10,15 +10,15 @@ Extension folder `Configuration/TCA` ==================================== -The folder :file:`EXT:my_extension/Configuration/TCA/` may contain or override +The folder :file:`EXT:my_extension/Configuration/TCA/` can contain or override :ref:`TCA (Table Configuration Array) ` data. -All files in this directory are automatically included during the TYPO3 +All files in this directory are automatically included during TYPO3 :ref:`bootstrap `. -Files within :file:`Configuration/TCA/` files are loaded within a dedicated scope. -This means that variables defined in those files cannot leak to any other -TCA file during the TCA compilation process. +Files in :file:`Configuration/TCA/` are loaded in a dedicated scope. +This means that variables defined in the files cannot leak to other +TCA files during the TCA compilation process. .. _extension-configuration-tca-table: diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/TsConfig/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/TsConfig/Index.rst index 02c00f68c2..b48950b3dc 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/TsConfig/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/TsConfig/Index.rst @@ -9,9 +9,9 @@ .. versionadded:: 13.1 Page TSconfig can be set using - `the site et as Page TSconfig provider `_ + `the site set as a Page TSconfig provider `_ - Default user TSconfig can be provided in file + Default user TSconfig can be put in the file :ref:`extension-configuration-user_tsconfig`. .. typo3:file:: something.tsconfig diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.rst index 84189eb15a..417b1c1871 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.rst @@ -9,17 +9,17 @@ ================== .. versionchanged:: 13.1 - Until TYPO3 v13 frontend TypoScript files where kept in folder + Until TYPO3 v13 frontend TypoScript files were kept in :path:`EXT:my_extension/Configuration/TypoScript/` by convention. - Extensions that need to be backward compatible should + Extensions that need to be backwardly compatible should `Support both site sets and TypoScript records `_. - Newly created extensions or site packages should use the + Newly created extensions and site packages should use a `Site set as a TypoScript provider `_ -TypoScript constants should be stored in a file called :file:`constants.typoscript` -and TypoScript setup in a file called :file:`setup.typoscript`. +TypoScript constants should be stored in the file :file:`constants.typoscript` +and TypoScript setup in :file:`setup.typoscript`. .. typo3:file:: constants.typoscript :scope: extension @@ -33,19 +33,19 @@ and TypoScript setup in a file called :file:`setup.typoscript`. :regex: /^.*Configuration\/TypoScript\/.*setup\.typoscript/ :shortDescription: Contains the TypoScript setup of the extension. The path is convention, the file name mandatory. -These two files are made available for inclusion in TypoScript records with -:php:`ExtensionManagementUtility::addStaticFile` in the file +These two files are made available for inclusion in TypoScript records by +:php:`ExtensionManagementUtility::addStaticFile` in :file:`Configuration/TCA/Overrides/sys_template.php`: .. literalinclude:: _snippets/_sys_template.php :caption: EXT:my_extension/Configuration/TCA/Overrides/sys_template.php -It is also possible to use subfolders or a differently named folder. The file -names have to stay exactly the same including case. +It is possible to use subfolders or a differently named folder instead, however, the file +names have to stay the same. .. warning:: - In Sites that use no Site set it is possible, though not recommended, - to provide TypoScript that is always included. + In Sites that don't use Site sets it is possible, though not recommended, + to have TypoScript that is always included. See :ref:`ext_typoscript_constants_typoscript` and :ref:`ext_typoscript_setup_typoscript`. These files are not included when - site uses a set. + a site uses a set. diff --git a/Documentation/ExtensionArchitecture/FileStructure/Configuration/UserTsconfig.rst b/Documentation/ExtensionArchitecture/FileStructure/Configuration/UserTsconfig.rst index 5783e3be15..b56d1049ec 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Configuration/UserTsconfig.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Configuration/UserTsconfig.rst @@ -18,11 +18,11 @@ :regex: /^.*Configuration\/user\.tsconfig$/ :shortDescription: Global user TSconfig -In this file global :ref:`user TSconfig ` can be stored. It will -be automatically included for the whole TYPO3 installation during build time. +This file stores global :ref:`user TSconfig `. It is +automatically included for the whole TYPO3 installation during build time. -For details see -:ref:`Setting the user TSconfig globally `. +For details, see +:ref:`Setting user TSconfig globally `. .. code-block:: typoscript diff --git a/Documentation/ExtensionArchitecture/FileStructure/Index.rst b/Documentation/ExtensionArchitecture/FileStructure/Index.rst index b950a5e27b..08b7d5312f 100644 --- a/Documentation/ExtensionArchitecture/FileStructure/Index.rst +++ b/Documentation/ExtensionArchitecture/FileStructure/Index.rst @@ -7,14 +7,13 @@ File structure ============== -Lists reserved file and directory names within an extension. Also -lists file names that are used in a certain way by convention. +This chapter lists the reserved file and directory names in an extension and +file naming conventions. -This chapter should also help you to find your way around in -extensions and sitepackages that where automatically generated or -that you downloaded as an example. +It should also help you find your way around +automatically-generated or example extensions and sitepackages. -The following folders and files can typically be found in a TYPO3 extension: +The following folder and file structure is typical for a TYPO3 extension: .. directory-tree:: :level: 1 @@ -129,14 +128,14 @@ Files An extension consists of: -1. A directory named by the *extension key* (which is a worldwide unique - identification string for the extension), usually located in :file:`typo3conf/ext` - for local extensions, or :file:`typo3/sysext` for system extensions. +1. A directory named *extension key* (a worldwide unique + identification string for the extension), located in :file:`typo3conf/ext` + for local extensions or :file:`typo3/sysext` for system extensions. 2. Standard files with reserved names for configuration related to TYPO3 - (of which most are optional, see list below) + (most are optional, see list below) -3. Any number of additional files for the extension functionality itself. +3. Additional files for the main extension functionality. .. index:: Extension development; Reserved file names .. _extension-reserved-filenames: @@ -144,33 +143,30 @@ An extension consists of: Reserved file names =================== -Most of these files are not required, except of :file:`ext_emconf.php` +Most of these files are not required, except :file:`ext_emconf.php` in :ref:`Classic mode installations not based on Composer ` -and :file:`composer.json ` in :ref:`Composer installations ` -installations. +and :file:`composer.json ` in :ref:`Composer installations `. .. note:: It is recommended to keep :file:`ext_emconf.php` and :file:`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. + public extensions that are published in the TYPO3 Extension Repository (TER), and + to ensure compatibility with Composer and legacy installations. -Do not introduce your own files in the root directory of -extensions with the name prefix :file:`ext_`, because that is reserved. +Do not use the prefix :file:`ext_` in your extension names as this is a reserved name. .. _extension-reserved-folders: 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. +In the early days, extension authors "baked their own bread" when it came to +PHP class file locations, 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 :file:`Classes/` folder and using appropriate namespaces for the classes, -the system will be able to autoload these files. +Since the rise of Extbase, a general structure for file +locations inside extensions has become established. If extension authors +stick to this and the Coding Guidelines, many things become easier. For instance, if you put +your PHP classes into a :file:`Classes/` folder and use appropriate namespaces for the classes, +the system will autoload the files. Extension kickstarters like the :composer:`friendsoftypo3/extension-builder` will create the correct structure for you.