Deprecation: #97244 - CompositeExpression methods 'add()' and 'addMultiple()'

Description

doctrine/dbal deprecated multiple CompositeExpression methods CompositeExpression->add() and CompositeExpression->addMultiple(). Therefore, those methods have also been deprecated in the Core facade class (\TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression), to avoid shifting too far away.

Impact

Using CompositeExpression->add() and CompositeExpression->addMultiple() will trigger a PHP E_USER_DEPRECATED error when called.

Affected Installations

In general, instances with extensions that use the deprecated methods CompositeExpression->add() and CompositeExpression->addMultiple(). The extension scanner finds usages of CompositeExpression->addMultiple() with a weak match. The other method is not scanned, as its name is too common.

Migration

The deprecated methods CompositeExpression->add() and CompositeExpression->addMultiple() can be replaced by using the new method CompositeExpression->with().

Note

The replacement method CompositeExpression->with() has already been added in a forward-compatible way in TYPO3 v11. Thus giving extension developers the ability to adopt new methods and still being able to support multiple Core versions without workarounds.

For example, the following code:

use TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression;

$compositeExpression = CompositeExpression::or();

$compositeExpression->add(
    $queryBuilder->expr()->eq(
        'field',
        $queryBuilder->createNamedParameter($singleValue)
    )
);
$compositeExpression->addMultiple(
    [
        $queryBuilder->expr()->eq(
            'field',
            $queryBuilder->createNamedParameter($value1)
        ),
        $queryBuilder->expr()->eq(
            'field',
            $queryBuilder->createNamedParameter($value2)
        ),
        //...
    ]
);

should be replaced with:

use TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression;

$compositeExpression = CompositeExpression::or();

// note, you have to assign the return of with() to the
// variable, otherwise added elements are lost.
$compositeExpression = $compositeExpression->with(
    $queryBuilder->expr()->eq(
        'field',
        $queryBuilder->createNamedParameter($singleValue)
    )
);

// Note the spread operator for the array
$compositeExpression = $compositeExpression->with(
    ...[
        $queryBuilder->expr()->eq(
            'field',
            $queryBuilder->createNamedParameter($value1)
        ),
        $queryBuilder->expr()->eq(
            'field',
            $queryBuilder->createNamedParameter($value2)
        ),
        //...
    ]
);

The multi expression example can now also be replaced like this:

use TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression;

$compositeExpression = CompositeExpression::or();

// note, you have to assign the return of with() to the
// variable, otherwise added elements are lost.
$compositeExpression = $compositeExpression->with(
    $queryBuilder->expr()->eq(
      'field',
      $queryBuilder->createNamedParameter($value1)
    ),
    $queryBuilder->expr()->eq(
      'field',
      $queryBuilder->createNamedParameter($value2)
    ),
    //...
);

Extension developers may have used to loop over some data to build multiple expressions which should be connected with and or or, either adding each element with the deprecated add(...) method or collecting it in an array and using deprecated addMultiple(...) method. Both use cases can be replaced with with(...).

use TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression;

$compositeExpression = CompositeExpression::or();

foreach($array as $element) {
    // note, you have to assign the return of with() to the
    // variable, otherwise added elements are lost.
    $compositeExpression = $compositeExpression->with(
        $queryBuilder->expr()->eq(
            'field',
            $queryBuilder->createNamedParameter($element)
        )
    );
}

or

use TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression;

$compositeExpression = CompositeExpression::or();

$expressions = [];
foreach($array as $element) {
    $expressions[] = $queryBuilder->expr()->eq(
        'field',
        $queryBuilder->createNamedParameter($element)
    );
}

// note, you have to assign the return of with() to the
// variable, otherwise added elements are lost.
$compositeExpression = $compositeExpression->with(...$expressions);

Instead of using with() when collecting expressions in an array, it can be used when instantiating the composite expression after the expression collecting:

use TYPO3\CMS\Core\Database\Query\Expression\CompositeExpression;

$expressions = [];
foreach($array as $element) {
    $expressions[] = $queryBuilder->expr()->eq(
        'field',
        $queryBuilder->createNamedParameter($element)
    );
}

$compositeExpression = CompositeExpression::or(...$expressions);