TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,102 @@
+.. include:: /Includes.rst.txt
+
+.. _breaking-102875-1706013339:
+
+=============================================
+Breaking: #102875 - ExpressionBuilder changes
+=============================================
+
+See :issue:`102875`
+
+Description
+===========
+
+Signature changes for following methods
+---------------------------------------
+
+*  :php:`ExpressionBuilder::literal(string $value)`: Value must be a string now.
+*  :php:`ExpressionBuilder::trim()`: Only :php:`\Doctrine\DBAL\Platforms\TrimMode`
+   enum for :php:`$position` argument.
+
+Following class constants have been removed
+-------------------------------------------
+
+*   :php:`QUOTE_NOTHING`: Not used since already TYPO3 v12 and Doctrine DBAL 3.x.
+*   :php:`QUOTE_IDENTIFIER`: Not used since already TYPO3 v12 and Doctrine DBAL 3.x.
+*   :php:`QUOTE_PARAMETER`: Not used since already TYPO3 v12 and Doctrine DBAL 3.x.
+
+Impact
+======
+
+Calling any of the mentioned methods with invalid type will result in a PHP
+error.
+
+Affected installations
+======================
+
+Only those installations that uses one of the mentioned methods with invalid type(s).
+
+Migration
+=========
+
+:php:`ExpressionBuilder::literal()`
+-----------------------------------
+
+Extension author need to ensure that a string is passed to :php:`literal()`.
+
+:php:`ExpressionBuilder::trim()`
+--------------------------------
+
+Extension author need to pass the Doctrine DBAL enum :php:`TrimMode` instead of
+an integer.
+
+TRIM_LEADING
+
+..  csv-table:: Replacements
+    :header: "integer", "enum"
+
+    0, "TrimMode::UNSPECIFIED"
+    1, "TrimMode::LEADING"
+    2, "TrimMode::TRAILING"
+    3, "TrimMode::BOTH"
+
+
+..  code-block:: php
+    :caption: EXT:my_extension/Classes/Domain/Repository/MyTableRepository.php
+
+    use Doctrine\DBAL\Platforms\TrimMode;
+    use TYPO3\CMS\Core\Database\Connection
+    use TYPO3\CMS\Core\Database\Query\Expression\ExpressionBuilder;
+
+    // before
+    $queryBuilder = $this->connectionPool->getQueryBuilderForTable('tt_content');
+    $queryBuilder->expr()->comparison(
+        $queryBuilder->expr()->trim($fieldName, 1),
+        ExpressionBuilder::EQ,
+        $queryBuilder->createNamedParameter('', Connection::PARAM_STR)
+    );
+
+    // after
+    $queryBuilder = $this->connectionPool->getQueryBuilderForTable('tt_content');
+    $queryBuilder->expr()->comparison(
+        $queryBuilder->expr()->trim($fieldName, TrimMode::LEADING),
+        ExpressionBuilder::EQ,
+        $queryBuilder->createNamedParameter('', Connection::PARAM_STR)
+    );
+
+    // example for dual version compatible code
+    $queryBuilder = $this->connectionPool->getQueryBuilderForTable('tt_content');
+    $queryBuilder->expr()->comparison(
+        $queryBuilder->expr()->trim($fieldName, TrimMode::LEADING),
+        ExpressionBuilder::EQ,
+        $queryBuilder->createNamedParameter('', Connection::PARAM_STR)
+    );
+
+..  tip::
+
+    With Doctrine DBAL 3.x the :php:`TrimMode` was a class with class constants. Using
+    these no code changes are needed for TYPO3 v12 and v13 compatible code. Only
+    method call type hinting needs to be adjusted to use the enum instead of
+    int.
+
+.. index:: Database, PHP-API, NotScanned, ext:core