[TASK] Deprecate logic in LanguageService

The master $GLOBALS[LANG] object should have a more
streamlined API and some methods and public properties
are now deprecated, in order to make this API much more
stateless.

Resolves: #90964
Releases: master
Change-Id: I201cf1b7300e385e3b87ab282290aae8e27041da
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/64056


Tested-by: TYPO3com <noreply@typo3.com>
Tested-by: Georg Ringer <georg.ringer@gmail.com>
Tested-by: Daniel Goerz <daniel.goerz@posteo.de>
Reviewed-by: Georg Ringer <georg.ringer@gmail.com>
Reviewed-by: Daniel Goerz <daniel.goerz@posteo.de>

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

@@ -15,6 +15,8 @@ namespace TYPO3\CMS\Core\Localization;
  */
 
 use TYPO3\CMS\Core\Authentication\AbstractUserAuthentication;
+use TYPO3\CMS\Core\Compatibility\PublicMethodDeprecationTrait;
+use TYPO3\CMS\Core\Compatibility\PublicPropertyDeprecationTrait;
 use TYPO3\CMS\Core\Site\Entity\SiteLanguage;
 use TYPO3\CMS\Core\Utility\ArrayUtility;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
@@ -40,6 +42,19 @@ use TYPO3\CMS\Core\Utility\GeneralUtility;
  */
 class LanguageService
 {
+    use PublicPropertyDeprecationTrait;
+    use PublicMethodDeprecationTrait;
+
+    protected $deprecatedPublicProperties = [
+        'LL_files_cache' => 'The runtime cache variable is only used for internal purposes, and should never be accessed from the outside. Accessing this property will stop working in TYPO3 v11.0.',
+        'LL_labels_cache' => 'The runtime cache variable is only used for internal purposes, and should never be accessed from the outside. Accessing this property will stop working in TYPO3 v11.0.'
+    ];
+
+    protected $deprecatedPublicMethods = [
+        'debugLL' => 'Should never be called directly. use the "debugKey" to actually access the method.',
+        'getLLL' => 'Use "getLL()" or "sL()" instead as API methods.',
+    ];
+
     /**
      * This is set to the language that is currently running for the user
      *
@@ -59,14 +74,14 @@ class LanguageService
      *
      * @var array
      */
-    public $LL_files_cache = [];
+    protected $LL_files_cache = [];
 
     /**
      * Internal cache for ll-labels (filled as labels are requested)
      *
      * @var array
      */
-    public $LL_labels_cache = [];
+    protected $LL_labels_cache = [];
 
     /**
      * List of language dependencies for actual language. This is used for local variants of a language
@@ -103,6 +118,7 @@ class LanguageService
      *
      * @throws \RuntimeException
      * @param string $languageKey The language key (two character string from backend users profile)
+     * @internal use one of the factory methods instead
      */
     public function init($languageKey)
     {
@@ -125,7 +141,7 @@ class LanguageService
      * @param string $value value to debug
      * @return string
      */
-    public function debugLL($value)
+    protected function debugLL($value)
     {
         return $this->debugKey ? '[' . $value . ']' : '';
     }
@@ -149,7 +165,7 @@ class LanguageService
      * @param array $localLanguage $LOCAL_LANG array to get label key from
      * @return string
      */
-    public function getLLL($index, $localLanguage)
+    protected function getLLL($index, $localLanguage)
     {
         // Get Local Language. Special handling for all extensions that
         // read PHP LL files and pass arrays here directly.
@@ -213,6 +229,7 @@ class LanguageService
      * $TCA_DESCR is a global var
      *
      * @param string $table Table name found as key in global array $TCA_DESCR
+     * @internal
      */
     public function loadSingleTableDescription($table)
     {
@@ -386,10 +403,11 @@ class LanguageService
      * @param string $prefix Prefix to select the correct labels
      * @param string $strip Sub-prefix to be removed from label names in the result
      * @return array Processed labels
-     * @todo: deprecate
+     * @deprecated will be removed in TYPO3 v11.0
      */
     public function getLabelsWithPrefix($prefix, $strip = '')
     {
+        trigger_error('LanguageService->getLabelsWithPrefix() will be removed in TYPO3 v11.0. Prefixing labels was used for various Backend-related JavaScript calls, which is not supported anymore. Prefixes should be applied to the label keys / ids directly instead.', E_USER_DEPRECATED);
         $extraction = [];
         if (!empty($GLOBALS['LOCAL_LANG']['default'])) {
             $labels = array_merge((array)$GLOBALS['LOCAL_LANG']['default'], (array)$GLOBALS['LOCAL_LANG'][$this->lang]);

typo3/sysext/core/Documentation/Changelog/master/Deprecation-90964-LanguageServiceFunctionalityAndInternalProperties.rst

+.. include:: ../../Includes.txt
+
+===========================================================================
+Deprecation: #90964 - LanguageService functionality and internal properties
+===========================================================================
+
+See :issue:`90964`
+
+Description
+===========
+
+LanguageService - also known as :php:`$GLOBALS[LANG]` within TYPO3 Core
+is used to fetch a label string from a XLF file and deliver the
+translated value from that string.
+
+Some functionality related to legacy functionality or internal logic has been deprecated and changed visibility:
+* :php:`LanguageService->LL_files_cache` - is now protected instead of public
+* :php:`LanguageService->LL_labels_cache` - is now protected instead of public
+* :php:`LanguageService->getLabelsWithPrefix()` - is deprecated as it is not needed
+* :php:`LanguageService->getLLL()` - is now protected instead of public
+* :php:`LanguageService->debugLL()` - is now protected instead of public
+
+The method :php:`LanguageService->loadSingleTableDescription()` is marked as internal now.
+
+
+Impact
+======
+
+Calling any of the methods or properties from above will trigger a PHP deprecation warning.
+
+
+Affected Installations
+======================
+
+TYPO3 installations with extensions of custom logic using the internals of specifics of the LanguageService class.
+
+
+Migration
+=========
+
+Use the Public API of the LanguageService - namely :php:`sL()` and :php:`getLL()` directly.
+
+.. index:: PHP-API, FullyScanned, ext:core

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

@@ -4462,4 +4462,25 @@ return [
             'Deprecation-90861-Image-relatedMethodsWithinContentObjectRenderer.rst',
         ],
     ],
+    'TYPO3\CMS\Core\Localization\LanguageService->getLabelsWithPrefix' => [
+        'numberOfMandatoryArguments' => 1,
+        'maximumNumberOfArguments' => 2,
+        'restFiles' => [
+            'Deprecation-90964-LanguageServiceFunctionalityAndInternalProperties.rst',
+        ],
+    ],
+    'TYPO3\CMS\Core\Localization\LanguageService->getLLL' => [
+        'numberOfMandatoryArguments' => 2,
+        'maximumNumberOfArguments' => 2,
+        'restFiles' => [
+            'Deprecation-90964-LanguageServiceFunctionalityAndInternalProperties.rst',
+        ],
+    ],
+    'TYPO3\CMS\Core\Localization\LanguageService->debugLL' => [
+        'numberOfMandatoryArguments' => 1,
+        'maximumNumberOfArguments' => 1,
+        'restFiles' => [
+            'Deprecation-90964-LanguageServiceFunctionalityAndInternalProperties.rst',
+        ],
+    ],
 ];

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

@@ -1258,4 +1258,14 @@ return [
             'Deprecation-89468-DeprecateInjectionOfEnvironmentServiceInWebRequest.rst',
         ],
     ],
+    'TYPO3\CMS\Core\Localization\LanguageService->LL_files_cache' => [
+        'restFiles' => [
+            'Deprecation-90964-LanguageServiceFunctionalityAndInternalProperties.rst',
+        ],
+    ],
+    'TYPO3\CMS\Core\Localization\LanguageService->LL_labels_cache' => [
+        'restFiles' => [
+            'Deprecation-90964-LanguageServiceFunctionalityAndInternalProperties.rst',
+        ],
+    ],
 ];