[TASK] Deprecate usage of $GLOBALS[LOCAL_LANG]

Instead of juggling with the globals, this should be handled within
the same LanguageService instance that knows the language
that was fetched.

Instead LanguageService now always returns the loaded
labels from the given file.

Resolves: #88567
Releases: master
Change-Id: Ie6a0367712625358b2c95b556c9fb0590e0d52ab
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/60878


Tested-by: TYPO3com <noreply@typo3.com>
Tested-by: Daniel Goerz <daniel.goerz@posteo.de>
Tested-by: Andreas Fernandez <a.fernandez@scripting-base.de>
Reviewed-by: Daniel Goerz <daniel.goerz@posteo.de>
Reviewed-by: Andreas Fernandez <a.fernandez@scripting-base.de>

typo3/sysext/backend/Classes/Controller/ContentElement/NewContentElementController.php

@@ -28,7 +28,6 @@ use TYPO3\CMS\Core\Imaging\Icon;
 use TYPO3\CMS\Core\Localization\LanguageService;
 use TYPO3\CMS\Core\Service\DependencyOrderingService;
 use TYPO3\CMS\Core\Type\Bitmask\Permission;
-use TYPO3\CMS\Core\Utility\ArrayUtility;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
 use TYPO3\CMS\Core\Utility\HttpUtility;
 use TYPO3\CMS\Fluid\View\StandaloneView;
@@ -152,10 +151,7 @@ class NewContentElementController
     {
         $lang = $this->getLanguageService();
         $lang->includeLLFile('EXT:core/Resources/Private/Language/locallang_misc.xlf');
-        $LOCAL_LANG_orig = $GLOBALS['LOCAL_LANG'];
         $lang->includeLLFile('EXT:backend/Resources/Private/Language/locallang_db_new_content_el.xlf');
-        ArrayUtility::mergeRecursiveWithOverrule($LOCAL_LANG_orig, $GLOBALS['LOCAL_LANG']);
-        $GLOBALS['LOCAL_LANG'] = $LOCAL_LANG_orig;
 
         $parsedBody = $request->getParsedBody();
         $queryParams = $request->getQueryParams();

typo3/sysext/core/Classes/Localization/LanguageService.php

@@ -70,6 +70,11 @@ class LanguageService
      */
     protected $languageFileCache = [];
 
+    /**
+     * @var string[][]
+     */
+    protected $labels = [];
+
     /**
      * LanguageService constructor.
      */
@@ -122,7 +127,7 @@ class LanguageService
      */
     public function getLL($index)
     {
-        return $this->getLLL($index, $GLOBALS['LOCAL_LANG']);
+        return $this->getLLL($index, !empty($GLOBALS['LOCAL_LANG']) ? $GLOBALS['LOCAL_LANG'] : $this->labels);
     }
 
     /**
@@ -206,7 +211,7 @@ class LanguageService
             $GLOBALS['TCA_DESCR'][$table]['columns'] = [];
             // Get local-lang for each file in $TCA_DESCR[$table]['refs'] as they are ordered.
             foreach ($GLOBALS['TCA_DESCR'][$table]['refs'] as $llfile) {
-                $localLanguage = $this->includeLLFile($llfile, false, true);
+                $localLanguage = $this->includeLanguageFileRaw($llfile);
                 // Traverse all keys
                 if (is_array($localLanguage['default'])) {
                     foreach ($localLanguage['default'] as $lkey => $lVal) {
@@ -258,19 +263,29 @@ class LanguageService
      * Read language labels will be merged with $LOCAL_LANG (if $setGlobal = TRUE).
      *
      * @param string $fileRef $fileRef is a file-reference
-     * @param bool $setGlobal Setting in global variable $LOCAL_LANG (or returning the variable)
-     * @param bool $mergeLocalOntoDefault
-     * @return mixed if $setGlobal===TRUE, LL-files set $LOCAL_LANG in global scope, or array is returned from function
+     * @param bool $setGlobal Setting in global variable $LOCAL_LANG (or returning the variable), do not set this, will be dropped in TYPO3 v11.0
+     * @param bool $mergeLocalOntoDefault, do not set this, will be dropped in TYPO3 v11.0
+     * @return array returns the loaded label file
      */
-    public function includeLLFile($fileRef, $setGlobal = true, $mergeLocalOntoDefault = false)
+    public function includeLLFile($fileRef, $setGlobal = null, $mergeLocalOntoDefault = null)
     {
+        if ($setGlobal !== null) {
+            trigger_error('LanguageService->includeLLFile() with the second argument set will be removed in TYPO3 v11.0, use "includeLLFile()" with only the file reference.', E_USER_DEPRECATED);
+        } else {
+            $setGlobal = true;
+        }
+        if ($mergeLocalOntoDefault !== null) {
+            trigger_error('LanguageService->includeLLFile() with the third argument set will be removed in TYPO3 v11.0, use "includeLLFile()" with only the file reference.', E_USER_DEPRECATED);
+        } else {
+            $mergeLocalOntoDefault = false;
+        }
         $globalLanguage = [];
         // Get default file
         $localLanguage = $this->readLLfile($fileRef);
         if (is_array($localLanguage) && !empty($localLanguage)) {
             // it depends on, whether we should return the result or set it in the global $LOCAL_LANG array
             if ($setGlobal) {
-                $globalLanguage = (array)($GLOBALS['LOCAL_LANG'] ?? []);
+                $globalLanguage = (array)($GLOBALS['LOCAL_LANG'] ?? $this->labels ?: []);
                 ArrayUtility::mergeRecursiveWithOverrule($globalLanguage, $localLanguage);
             } else {
                 $globalLanguage = $localLanguage;
@@ -287,8 +302,31 @@ class LanguageService
         if (!$setGlobal) {
             return $globalLanguage;
         }
+        $this->labels = $globalLanguage;
         $GLOBALS['LOCAL_LANG'] = $globalLanguage;
-        return null;
+        return $localLanguage;
+    }
+
+    /**
+     * Includes a locallang file (and possibly additional localized version if configured for),
+     * and then puts everything into "default", so "default" is kept as fallback
+     *
+     * @param string $fileRef $fileRef is a file-reference
+     * @return array
+     */
+    protected function includeLanguageFileRaw($fileRef)
+    {
+        $labels = $this->readLLfile($fileRef);
+        if (is_array($labels) && !empty($labels)) {
+            // Merge local onto default
+            if ($this->lang !== 'default' && is_array($labels[$this->lang]) && is_array($labels['default'])) {
+                // array_merge can be used so far the keys are not
+                // numeric - which we assume they are not...
+                $labels['default'] = array_merge($labels['default'], $labels[$this->lang]);
+                unset($labels[$this->lang]);
+            }
+        }
+        return is_array($labels) ? $labels : [];
     }
 
     /**
@@ -340,7 +378,11 @@ class LanguageService
     public function getLabelsWithPrefix($prefix, $strip = '')
     {
         $extraction = [];
-        $labels = array_merge((array)$GLOBALS['LOCAL_LANG']['default'], (array)$GLOBALS['LOCAL_LANG'][$this->lang]);
+        if (!empty($GLOBALS['LOCAL_LANG']['default'])) {
+            $labels = array_merge((array)$GLOBALS['LOCAL_LANG']['default'], (array)$GLOBALS['LOCAL_LANG'][$this->lang]);
+        } else {
+            $labels = array_merge((array)$this->labels['default'], (array)$this->labels[$this->lang]);
+        }
         // Regular expression to strip the selection prefix and possibly something from the label name:
         $labelPattern = '#^' . preg_quote($prefix, '#') . '(' . preg_quote($strip, '#') . ')?#';
         // Iterate through all locallang labels:

typo3/sysext/core/Documentation/Changelog/master/Deprecation-88567-GLOBALS_LOCAL_LANG.rst

+.. include:: ../../Includes.txt
+
+============================================
+Deprecation: #88567 - $GLOBALS['LOCAL_LANG']
+============================================
+
+See :issue:`88567`
+
+Description
+===========
+
+The global array :php:`$GLOBALS['LOCAL_LANG']` contains all labels from language
+files that were loaded "globally". However, instead of having this in global
+scope, it is more feasible to have it scoped to the actual :php:`LanguageService`
+that loaded this data, in order to allow various language functionality in the
+same PHP process without having to deal with global variables.
+
+For this reason, it is discouraged to use the :php:`$GLOBALS['LOCAL_LANG']`
+but instead rely on :php:`LanguageService->includeLLfile()` which returns
+the actual values as well, but only the ones loaded from this instance.
+
+Since LanguageService is usually available via `$GLOBALS['LANG']` the
+labels are accessible within PHP anyways.
+
+Due to this change, the second and third arguments of
+:php:`LanguageService->includeLLFile()` have been deprecated.
+
+
+Impact
+======
+
+Calling the method above with an explicit second and/or third argument will
+trigger a PHP deprecation warning.
+
+
+Affected Installations
+======================
+
+Any TYPO3 installation with third-party extensions using
+:php:`$GLOBALS['LOCAL_LANG']` or the mentioned method with more than one argument,
+which is very unlikely.
+
+
+Migration
+=========
+
+Use the return value of :php:`LanguageService->includeLLFile()` and remove
+the second and third arguments to work with label files.
+
+.. index:: PHP-API, FullyScanned
\ No newline at end of file

typo3/sysext/install/Configuration/ExtensionScanner/Php/ArrayGlobalMatcher.php

@@ -36,4 +36,9 @@ return [
             'Breaking-88498-GlobalDataForTimeTrackerStatisticsRemoved.rst',
         ],
     ],
+    '$GLOBALS[\'LOCAL_LANG\']' => [
+        'restFiles' => [
+            'Deprecation-88567-GLOBALS_LOCAL_LANG.rst',
+        ],
+    ],
 ];

typo3/sysext/install/Configuration/ExtensionScanner/Php/MethodArgumentDroppedMatcher.php

@@ -229,4 +229,10 @@ return [
             'Breaking-88574-4thParameterOfPageRepository-enableFieldsRemoved.rst',
         ],
     ],
+    'TYPO3\CMS\Core\Localization\LanguageService->includeLLFile' => [
+        'maximumNumberOfArguments' => 1,
+        'restFiles' => [
+            'Deprecation-88567-GLOBALS_LOCAL_LANG.rst',
+        ],
+    ],
 ];