[FEATURE] Add castText() expression support to ExpressionBuilder (#5350)

* [FEATURE] Add castText() expression support to ExpressionBuilder

Resolves: TYPO3-Documentation/Changelog-To-Doc#978
Releases: main, 13.4

* [FEATURE] Add castText() expression support to ExpressionBuilder

Resolves: TYPO3-Documentation/Changelog-To-Doc#978
Releases: main, 13.4

Author: linawolf

Documentation/ApiOverview/Database/ExpressionBuilder/Index.rst

@@ -236,6 +236,28 @@ is used.
     :language: php
     :caption: EXT:my_extension/Classes/Domain/Repository/MyTableRepository.php
 
+..  _database-expression-builder-castText:
+
+:php:`ExpressionBuilder::castText()`
+------------------------------------
+
+..  versionadded:: 13.3
+
+..  todo: Add api description as soon as building code-snippets is working again
+
+Can be used to create an expression which converts a value, row field value or
+the result of an expression to type `TEXT` or a large `VARCHAR, depending on the
+database system in use.
+
+Casting is done to large :sql:`VARCHAR/CHAR` types using the :sql:`CAST/CONVERT`
+or similar methods based on the used database engine.
+
+..  include:: _EscapeWarning.rst.txt
+
+..  literalinclude:: _RepositoryCastText.php
+    :language: php
+    :caption: EXT:my_extension/Classes/Domain/Repository/MyTableRepository.php
+
 ..  _database-expression-builder-castVarchar:
 
 :php:`ExpressionBuilder::castVarchar()`

Documentation/ApiOverview/Database/ExpressionBuilder/_RepositoryCastText.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Domain\Repository;
+
+use TYPO3\CMS\Core\Database\ConnectionPool;
+
+final class MyTableRepository
+{
+    private const TABLE_NAME = 'my_table';
+
+    public function __construct(private readonly ConnectionPool $connectionPool) {}
+
+    public function demonstrateCastText(string $col1, string $col2): array
+    {
+        $queryBuilder = $this->connectionPool
+            ->getQueryBuilderForTable(self::TABLE_NAME);
+
+        return $queryBuilder
+            ->selectLiteral(
+                $queryBuilder->quoteIdentifier($col1),
+                $queryBuilder->quoteIdentifier($col2),
+                // !!! Escape all values passed to castText to prevent SQL injections
+                $queryBuilder->expr()->castText(
+                    $queryBuilder->quoteIdentifier($col2) . ' * 10',
+                    'virtual_field',
+                ),
+            )
+            ->from(self::TABLE_NAME)
+            ->executeQuery()
+            ->fetchAllAssociative();
+    }
+}