From 480828c309c8cf59f7aa4f12a8b2422ae77224e4 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Mon, 16 Sep 2024 12:38:24 +0200 Subject: [PATCH] [DOCS] Document database records (#4760) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [DOCS] Document database records A detailed explanation of what they are was missing. This is a preparation for documenting the v13 additions of record objects. Releases: main, 11.5 * Update Documentation/ApiOverview/Database/Index.rst Co-authored-by: Stefan Frömken * Apply suggestions from code review Co-authored-by: Stefan Frömken * Apply suggestions from code review Co-authored-by: Stefan Frömken * Update Documentation/ApiOverview/DatabaseRecords/Index.rst Co-authored-by: Stefan Frömken * Update Documentation/ApiOverview/Database/Index.rst Co-authored-by: Stefan Frömken * Update Documentation/ApiOverview/Database/Index.rst * Update Index.rst * Update Index.rst * [DOCS] Document database records A detailed explanation of what they are was missing. This is a preparation for documenting the v13 additions of record objects. Releases: main, 11.5 --------- Co-authored-by: Stefan Frömken --- .../ApiOverview/Categories/Index.rst | 3 +- .../ApiOverview/ContentElements/Index.rst | 6 +- Documentation/ApiOverview/Database/Index.rst | 59 ++++++---- .../ApiOverview/DatabaseRecords/Index.rst | 110 ++++++++++++++++++ .../Extbase/Reference/Domain/Model.rst | 2 + 5 files changed, 157 insertions(+), 23 deletions(-) create mode 100644 Documentation/ApiOverview/DatabaseRecords/Index.rst diff --git a/Documentation/ApiOverview/Categories/Index.rst b/Documentation/ApiOverview/Categories/Index.rst index 7a92e3134c..5edc4ec4dc 100644 --- a/Documentation/ApiOverview/Categories/Index.rst +++ b/Documentation/ApiOverview/Categories/Index.rst @@ -7,7 +7,8 @@ System categories ================= TYPO3 provides a generic categorization system. -Categories can be created in the backend like any other type of record. +Categories can be created in the backend like any other type of +:ref:`record `. A TCA field of the column type :ref:`category` is available. diff --git a/Documentation/ApiOverview/ContentElements/Index.rst b/Documentation/ApiOverview/ContentElements/Index.rst index 4e9b9b7cdb..2c09588e08 100644 --- a/Documentation/ApiOverview/ContentElements/Index.rst +++ b/Documentation/ApiOverview/ContentElements/Index.rst @@ -28,7 +28,11 @@ Introduction .. contents:: :local: -In TYPO3, content elements and plugins are both used to present and manage +In TYPO3, Content elements and plugins are both stored as :ref:`database-records` +in table :sql:`tt_content`. They are usually edited in the backend in module +:guilabel:`Web > Page`. + +Content elements and plugins are both used to present and manage content on a website, but they serve different purposes and have distinct characteristics: diff --git a/Documentation/ApiOverview/Database/Index.rst b/Documentation/ApiOverview/Database/Index.rst index 2ca1b5a366..0a73d2e8e5 100644 --- a/Documentation/ApiOverview/Database/Index.rst +++ b/Documentation/ApiOverview/Database/Index.rst @@ -1,29 +1,46 @@ :navigation-title: Database -.. include:: /Includes.rst.txt -.. index:: ! Database -.. _database: +.. include:: /Includes.rst.txt +.. index:: ! Database +.. _database: ======================== Database (Doctrine DBAL) ======================== -**Contents:** +This chapter describes accessing the database on the level of the Doctrine +Database Abstraction Layer (DBAL). -.. toctree:: - :titlesonly: +The `Doctrine Database Abstraction Layer (DBAL) `__ in TYPO3 provides developers +with a powerful and flexible way to interact with databases, allowing them to +perform database operations through an object-oriented API while ensuring +compatibility across different database systems. - Introduction/Index - Configuration/Index - DatabaseStructure/Index - DatabaseUpgrade/Index - BasicCrud/Index - ClassOverview/Index - ConnectionPool/Index - QueryBuilder/Index - Connection/Index - ExpressionBuilder/Index - RestrictionBuilder/Index - Statement/Index - Middleware/Index - TipsAndTricks/Index - Troubleshooting/Index +Within the TYPO3 backend rows of database tables are usually represented as +:ref:`database-records` and configured in :ref:`database-records-tca`. + +In Extbase based extensions tables are abstracted as +:ref:`Extbase models `. Operations such as creating, updating and +deleting database records are usually performed from within a +:ref:`Extbase repository ` with methods provided by Extbase +classes. However, Doctrine DBAL can also be used by extensions that use, for +example an :ref:`Extbase controller `. + +.. toctree:: + :caption: Contents + :titlesonly: + + Introduction/Index + Configuration/Index + DatabaseStructure/Index + DatabaseUpgrade/Index + BasicCrud/Index + ClassOverview/Index + ConnectionPool/Index + QueryBuilder/Index + Connection/Index + ExpressionBuilder/Index + RestrictionBuilder/Index + Statement/Index + Middleware/Index + TipsAndTricks/Index + Troubleshooting/Index diff --git a/Documentation/ApiOverview/DatabaseRecords/Index.rst b/Documentation/ApiOverview/DatabaseRecords/Index.rst new file mode 100644 index 0000000000..2a3be723d7 --- /dev/null +++ b/Documentation/ApiOverview/DatabaseRecords/Index.rst @@ -0,0 +1,110 @@ +:navigation-title: Database records +.. include:: /Includes.rst.txt +.. _database-records: + +================ +Database records +================ + +In TYPO3, a **record** refers to an individual piece of content or data that +is stored in the database. Each record is part of a table and represents a +specific entity, such as a page, a content element, a backend user, or an +extension configuration. + +TYPO3 uses a modular structure where different types of data are managed as +records, making it easy to organize and manipulate content. + +Understanding records in TYPO3 is fundamental, as they are the building blocks +for managing content and data within the system. + +.. contents:: + :caption: Content on this page + +.. _database-records-examples: + +Common examples of records in TYPO3: +==================================== + +Page records + These represent pages in the page tree, which structure the website. They + are stored in table :sql:`pages`. +Content records + These include text, images, videos, or any other element placed within a + page. They are stored in table :sql:`tt_content`. +Backend user records + Information about users who have access to the TYPO3 backend. They + are stored in table :sql:`be_users`. The backend user groups they are + organized in are stored in table :sql:`be_groups`. +System records + System records control the configuration and management of the TYPO3 system. + Examples include file references, file mounts, or categories. +Extension-specific records + Extensions often define custom records to store specific data, such as + products for a shop system or events for a calendar. + +.. todo: Create a page listing all tables created by the core and explain what + they do. Link from here + +.. _database-records-technical: + +Technical structure of a record: +================================ + +Each record is stored in a database table. Each row represents one record. Each +column represents a field of the record or some kind of metadata. + +A record typically includes a unique identifier in column `uid`, the id of the +page record on which it is located in column `pid`, columns for various +attributes (for example, title, content), and metadata like creation and +modification timestamps, visibility, information on translation +and workspace handling. A record can have relations to other records. + +.. _database-records-tca: + +TCA (Table Configuration Array) +=============================== + +TYPO3 uses the **TCA** to define how records of a specific table are +structured, how they are displayed in the backend, and how they interact +with other parts of the system. See the :ref:`TCA Reference ` +for details. + +.. _database-records-types: + +Types and subtypes in records +----------------------------- + +In TYPO3, different types and subtypes of records are often stored in the same +database table, even though not all types share the same columns. This approach +allows for flexibility and efficiency in handling diverse content and data +structures within a unified system. + +TYPO3 uses a **single-table inheritance** strategy, where records of various +types are distinguished by a specific field, often named :sql:`type`. +For historical reasons the field is named :sql:`CType` for content elements +and :sql:`doktype` for pages. The field that is used for the type is defined in +TCA in :confval:`ctrl > type `. The types itself are stored in +:ref:`types `. + +This allows TYPO3 to store related records, such as different content types, +in a shared table like :sql:`tt_content` while supporting custom +fields for each record type. + +For content elements in table :sql:`tt_content` there is a second level of +subtypes in use where the field `CType` contains the value "list" and the field +`list-type` contains the actual type. This second level of types exists for +historic reasons. Read more about it in chapter :ref:`content-element-and-plugin`. + +.. _database-records-models: + +Extbase domain models +===================== + +TYPO3 extensions based on Extbase typically introduce a class inheriting from +:php:`\TYPO3\CMS\Extbase\DomainObject\AbstractEntity` to represent a record +fully or partially within the domain of the extension. Multiple Extbase models +can store their data in the same database table. Additionally, the same record +can be represented in various ways by different Extbase models, depending on +the specific requirements of each model. + +See also chapter :ref:`Extbase models `. diff --git a/Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model.rst b/Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model.rst index 15ff43be0b..86494d8541 100644 --- a/Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model.rst +++ b/Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model.rst @@ -24,6 +24,8 @@ thread of continuity and identity, for example, a person or a blog post. Objects stored in the database are usually entities as they can be identified by the :sql:`uid` and are persisted, therefore have continuity. +In the TYPO3 backend models are displayed as :ref:`database-records`. + **Example:** .. include:: /CodeSnippets/Extbase/Domain/AbstractEntity.rst.txt