TYPO3 v15 dev-main snapshot ()

Documentation/Changelog/9.3/Deprecation-84993-DeprecateSomeTSconfigRelatedMethods.rst

@@ -0,0 +1,107 @@
+.. include:: /Includes.rst.txt
+
+.. _deprecation-84993:
+
+=============================================================
+Deprecation: #84993 - Deprecate some TSconfig related methods
+=============================================================
+
+See :issue:`84993`
+
+Description
+===========
+
+Some user TSconfig related methods have been deprecated:
+
+* :php:`TYPO3\CMS\core\Authentication\BackendUserAuthentication->getTSConfigVal()`
+* :php:`TYPO3\CMS\core\Authentication\BackendUserAuthentication->getTSConfigProp()`
+
+Changed method signatures:
+
+* :php:`TYPO3\CMS\core\Authentication\BackendUserAuthentication->getTSConfig()`, no argument allowed any longer
+
+Some page TSconfig related methods have been marked as deprecated:
+
+* :php:`TYPO3\CMS\backend\Utility\BackendUtility::getModTSconfig()`
+* :php:`TYPO3\CMS\backend\Utility\BackendUtility::unsetMenuItems()`
+* :php:`TYPO3\CMS\backend\Tree\View\PagePositionMap->getModConfig()`
+* :php:`TYPO3\CMS\core\DataHandling\DataHandler->getTCEMAIN_TSconfig()`
+
+These properties have been set to protected, should not be used any longer and trigger a deprecation error on access:
+
+* :php:`TYPO3\CMS\backend\Tree\View\PagePositionMap->getModConfigCache`
+* :php:`TYPO3\CMS\backend\Tree\View\PagePositionMap->modConfigStr`
+
+
+Impact
+======
+
+Calling the above methods will trigger a PHP :php:`E_USER_DEPRECATED` error.
+
+
+Affected Installations
+======================
+
+Extensions with backend modules may call these methods. The extension scanner
+will find affected code occurrences in extensions.
+
+
+Migration
+=========
+
+Change user TSconfig related calls to use :php:`BackendUserAuthentication->getTSConfig()`
+instead, it comes with a slightly changed return syntax.
+
+:php:`getTSConfig()` without arguments simply returns the entire user TSconfig as array, similar to other
+methods that return parsed TypoScript arrays. The examples below show some imaginary user TSConfig,
+the full parsed array returned by :php:`getTSConfig()` and some typical access patterns with fallback. Note
+it's almost always useful to use the null coalescence :php:`??` operator for a fallback value to suppress
+PHP notice level warnings::
+
+    // Incoming user TSconfig:
+    // options.someToggle = 1
+    // options.somePartWithSubToggles = foo
+    // options.somePartWithSubToggles.aValue = bar
+
+    // Parsed array returned by getTSConfig(), note the dot if a property has sub keys:
+    // [
+    //     'options.' => [
+    //         'someToggle' => '1',
+    //         'somePartWithSubToggles' => 'foo',
+    //         'somePartWithSubToggles.' => [
+    //             'aValue' => 'bar',
+    //         ],
+    //     ],
+    // ],
+    $userTsConfig = $backendUserAuthentication->getTSConfig():
+
+    // Typical call to retrieve a sanitized value:
+    $isToggleEnabled = (bool)($userTsConfig['options.']['someToggle'] ?? false);
+
+    // And to retrieve a sub set, note the dot at the end:
+    $subArray = $userTsConfig['options.']['somePartWithSubToggles.'] ?? [];
+
+    // Switch an old getTSConfigVal() to getTSConfig(), note the parenthesis:
+    $value = (bool)$backendUser->getTSConfigVal('options.someToggle');
+    $value = (bool)($backendUser->getTSConfig()['options.']['someToggle'] ?? false);
+
+    // Switch an old getTSConfigProp() to getTSConfig(), note the parenthesis and the trailing dot:
+    $value = (array)$backendUser->getTSConfigProp('options.somePartWithSubToggles');
+    $value = (array)($backendUser->getTSConfig()['options.']['somePartWithSubToggles.'] ?? []);
+
+
+Change :php:`BackendUtility->getModTSconfig()` related calls to use :php:`BackendUtility::getPagesTSconfig($pid)` instead.
+Note this method does not return the 'properties' and 'value' sub array as :php:`->getModTSconfig()` did::
+
+    // Switch an old getModTSconfig() to getPagesTSConfig() for array of properties:
+    $configArray = BackendUtility::getModTSconfig($pid, 'mod.web_list');
+    $configArray['properties'] = BackendUtility::getPagesTSconfig($pid)['mod.']['web_list.'] ?? [];
+
+    // Switch an old getModTSconfig() to getPagesTSConfig() for single value:
+    $configArray = BackendUtility::getModTSconfig($pid, 'TCEFORM.sys_dmail_group.select_categories.PAGE_TSCONFIG_IDLIST');
+    $configArray['value'] = BackendUtility::getPagesTSconfig($pid)['TCEFORM.']['sys_dmail_group.']['select_categories.']['PAGE_TSCONFIG_IDLIST'] ?? null;
+
+Methods :php:`BackendUtility::unsetMenuItems()` and :php:`DataHandler->getTCEMAIN_TSconfig()` have been rarely used
+and are dropped without substitution. Copy the code into consuming methods if you really need them.
+
+.. index:: Backend, PHP-API, TSConfig, FullyScanned