[Backport 13.4] [TASK] Overhaul extension development howto model extensions (#6249)

* [TASK] Overhaul extension development howto model extensions

Releases: main, 13.4

* [TASK] Overhaul extension development howto model extensions

Releases: main, 13.4

---------

Co-authored-by: Sarah McCarthy <[email protected]>

Author: github-actions[bot]

Documentation/ExtensionArchitecture/HowTo/ExtendExtbaseModel/Index.rst

@@ -8,44 +8,48 @@
 Extending an Extbase model
 ==========================
 
-Once you have added an additional field to the
-:ref:`TCA <extending-tca>` the new field will be displayed in the backend forms.
+Once you have added a new field to the
+:ref:`TCA <extending-tca>` it will be displayed in the backend forms.
 
 However, if the extension you are trying to extend is based on :ref:`Extbase <extbase>` the new
 field is not available in the frontend out of the box. Further steps are
 needed to make the fields available. These steps will not work in all cases.
 
+.. _extending-extbase-model_quick_overview:
+
 Quick overview
 ==============
 
 Follow these steps:
 
 ..  rst-class:: bignums
 
-#.  Is your extension the :ref:`only one trying to
+#.  Is your extension the :ref:`only extension trying to
     extend <extending-extbase-model_find_other_extending_models>` the original
-    model within your installation?
+    model in your installation?
 
 #.  :ref:`Find the original model <extending-extbase-model_find_original_model>`.
-    If this model has the modifier :php:`final` refer
-    to the extension's documentation on how to display additional fields.
+    If the model has the :php:`final` modifier, refer
+    to the extension documentation on how to display additional fields.
 
 #.  :ref:`Find the original repository <extending-extbase-model_find_original_repository>`.
-    Again, if the repository is :php:`final` refer
-    to the extension's documentation on how to display additional fields.
+    If the repository is :php:`final`, refer
+    to the extension documentation on how to display additional fields.
 
 #.  :ref:`Extend the original model <extending-extbase-model_extend_original_model>`
-    in your custom extension or :ref:`sitepackage <site-package>`.
+    in your extension or :ref:`sitepackage <site-package>`.
 
 #.  :ref:`Register your extended model <extending-extbase-model_register_extended_model>`
-    with the according database table in
+    with the corresponding database table in
     :file:`EXT:my_extension/Configuration/Extbase/Persistence/Classes.php`.
 
 #.  :ref:`Extend the original repository <extending-extbase-model_register_extended_model>`
-    in your custom extension or sitepackage.
+    in your extension or sitepackage.
 
 #.  :ref:`Register your extended repository <extending-extbase-model_register_extended_repository>`
-    to be used instead of the original one.
+    so that it is used instead of the original one.
+
+.. _extending-extbase-model_steps:
 
 Step by step
 ============
@@ -55,49 +59,49 @@ Step by step
 Are you the only one trying to extend that model?
 -------------------------------------------------
 
-Within your installation you can search for other classes that are extending
+Search for other classes in your installation that extend
 the original model or repository (see below).
 
 If the model is already extended but you only need to create the fields for
 your current installation you can proceed by extending the extended model.
-In the following steps of this tutorial use the previously extended model
-as original model.
+In the rest of this tutorial use the extended model
+as the original model.
 
-If the model has different :ref:`Record types <extbase-persistance-record-types>`
-you can decide to introduce a new type and
-only extend that one type. This is, for example, commonly done when extending
-the model of :composer:`georgringer/news`.
+If the model has different :ref:`record types <extbase-persistance-record-types>`
+you can add a new type and
+only extend that one type. This is commonly done when extending
+the :composer:`georgringer/news` model.
 
-If you are planning to publish your extension that extends another extensions
-model, research on `Packagist <https://packagist.org/>`__ and the
+If you are planning to publish this extension, search
+`Packagist <https://packagist.org/>`__ and the
 `TER (TYPO3 extension repository) <https://extensions.typo3.org/>`__ for
-extensions that are already extending the model. If necessary, put them in
-the `conflict` sections of you extensions :ref:`composer-json` and
+extensions that also extend the original model. If necessary, put them in
+the `conflict` sections of your extension's :ref:`composer-json` and
 :ref:`ext_emconf-php`.
 
 ..  _extending-extbase-model_find_original_model:
 
-Find the original model
------------------------
+Finding the original model
+--------------------------
 
-The model should be located in the original extension at path
-:file:`EXT:original_extension/Classes/Domain/Model/` or a subdirectory
-thereof. If the model is not found here it might
+The model should be located in the original extension in
+:file:`EXT:original_extension/Classes/Domain/Model/` or a subdirectory. If the
+model is not there it might:
 
-*   be situated in a different extension
-*   not be an Extbase model (you cannot follow this tutorial then)
+*   be located in a different extension
+*   not be an Extbase model (then you cannot follow this tutorial)
 
-You can also try to debug the model in a Fluid template that outputs the model:
+You can also try debugging the model with a Fluid template that outputs the model:
 
 ..  code-block:: html
     :caption: Some Fluid template that uses the model
 
     <f:debug>{someModel}</f:debug>
 
-If you debugged the correct object the fully qualified PHP name of the model
-will appear in the debug output. This gives you further hints on where to find
+If you debugged the correct object, the fully qualified PHP name of the model
+will appear in the debug output. This will give you further hints on where to find
 the associated class. You could, for example, do a full text search for the
-namespace of this class.
+namespace of the class.
 
 If the class of the model is final:
 
@@ -108,56 +112,55 @@ If the class of the model is final:
         // ...
     }
 
-It cannot be extended by means of this tutorial. Refer to the documentation of
+it cannot be extended using the instructions in this tutorial. Refer to the documentation of
 the original extension.
 
 ..  _extending-extbase-model_find_original_repository:
 
-Find the original repository
-----------------------------
+Finding the original repository
+-------------------------------
 
-In Extbase the repository of a model mostly has to have the same class name as
-the model, prefixed with "Repository". It has to be located in the same domain
-directory as the model, but in the subfolder :file:`Repository`.
+In Extbase the repository of a model usually has the same class name as
+the model, prefixed with "Repository". It is located in the same domain
+directory as the model, but in the :file:`Repository` subfolder.
 
-For example, if the model is found in :file:`Classes/Domain/Model/SomeModel.php`
+For example, if the model is :file:`Classes/Domain/Model/SomeModel.php`
 the repository is located in
 :file:`Classes/Domain/Repository/SomeModelRepository.php`.
 
-*   If you do not find this repository but found the model the extension might
-    not use an Extbase repository. This tutorial does not help you in this
-    case as it can only be applied to Extbase repositories.
-*   If you find a repository in this name scheme but it does not extend
-    directly or indirectly the class
-    :php:`TYPO3\CMS\Extbase\Persistence\Repository` you are also not dealing
-    with an Extbase repository.
+*   If you can't find the repository but have found the model, the extension might
+    not be using an Extbase repository. This tutorial will not help you in this
+    case as it is only relevant for Extbase repositories.
+*   If you find a repository according to this naming scheme but it does not extend
+     the class
+    :php:`TYPO3\CMS\Extbase\Persistence\Repository` directly or indirectly, it
+    is also not an Extbase repository.
 *   If the repository is final it cannot be extended.
 
-In all these cases refer to the extension's documentation on how to extend it.
+In all these cases refer to the extension documentation on how to extend it.
 
 ..  _extending-extbase-model_extend_original_model:
 
 Extend the original model
 -------------------------
 
-We assume you already extended the database table and TCA (table configuration array)
-as described in :ref:`Extending TCA <extending-tca>`. Extend the
-original model by a custom class in your extension:
+We assume that you have already extended the database table and TCA (table
+configuration array) as described in :ref:`Extending TCA <extending-tca>`. Extend the
+original model in your extension using a class:
 
 ..  literalinclude:: _MyExtendedModel.php
     :language: php
     :caption: EXT:my_extension/Classes/Domain/Model/MyExtendedModel.php
 
-Add all additional fields that you require. By convention the database
-fields are usually prefixed with your extension's name and so are the
-names in the model.
+Add all the additional fields that you require. By convention the database
+fields and the model names are prefixed with the name of your extension.
 
 ..  _extending-extbase-model_register_extended_model:
 
 Register the extended model
 ---------------------------
 
-The extended model needs to be registered for :ref:`Extbase persistence <extbase-Persistence>` in file
+The extended model needs to be registered for :ref:`Extbase persistence <extbase-Persistence>` in files
 :file:`Configuration/Extbase/Persistence/Classes.php` and :file:`ext_localconf.php`.
 
 ..  literalinclude:: _Classes.php
@@ -173,44 +176,46 @@ The extended model needs to be registered for :ref:`Extbase persistence <extbase
 Extend the original repository (optional)
 -----------------------------------------
 
-Likewise extend the original repository:
+Similarly, extend the original repository:
 
 ..  literalinclude:: _MyExtendedModelRepository.php
     :language: php
     :caption: EXT:my_extension/Classes/Domain/Repository/MyExtendedModelRepository.php
 
-The rule that a repository must follow the name schema of the model also
+The rule that a repository must follow the naming schema of the model also
 applies when extending model and repository. So the new repository's name must
-end on "Repository" and it must be in the directory :file:`Domain/Repository`.
+end with "Repository" and it must be in the :file:`Domain/Repository` directory.
 
-If you have no need for additional repository methods you can leave the body of
-this class empty. However, for Extbase internal reasons you have to create this
-repository even if you need no additional functionality.
+If you don't need additional repository methods you can leave the body of
+this class empty. However, for internal Extbase reasons you have to create the
+repository even if you don't add additional functionality.
 
 ..  _extending-extbase-model_register_extended_repository:
 
 Register the extended repository
 --------------------------------
 
-The extended repository needs to be registered with Extbase in your extensions
-:file:`EXT:my_extension/ext_localconf.php`. This step tells
+The extended repository needs to be registered with Extbase in your extension file
+:file:`EXT:my_extension/ext_localconf.php`. This tells
 Extbase to use your repository instead of the original one whenever the original
 repository is requested via Dependency Injection in a controller or service.
 
 ..  literalinclude:: _ext_localconf_repository.php
     :language: php
     :caption: EXT:my_extension/ext_localconf.php
 
+..  _extending-extbase-model_alternative_strategies:
+
 Alternative strategies to extend Extbase models
 ===============================================
 
-There is a dedicated TYPO3 extension to extend models and functions to classes by
+There is a TYPO3 extension that extends models and functions to classes by
 implementing the proxy pattern: `Extbase Domain Model Extender
 (evoweb/extender) <https://extensions.typo3.org/extension/extender>`__.
 
-This extension can - for example - be used to
-:ref:`Extend models of tt_address <friendsoftypo3/tt-address:development-extend-ttaddress>`.
+This extension can be used to
+:ref:`extend models of tt_address <friendsoftypo3/tt-address:development-extend-ttaddress>`, for example.
 
-The commonly used extension `EXT:news (georgringer/news)` supplies a special
-generator that can be used to :ref:`add custom fields to news models
+The popular extension `EXT:news (georgringer/news)` has a special
+generator that can be used to :ref:`add new fields to news models
 <georgringer/news:proxyClassGenerator>`.