core/lib/Drupal.php

@@ -15,8 +15,9 @@
  *
  * The container is built by the kernel and passed in to this class which stores
  * it statically. The container always contains the services from
- * \Drupal\Core\CoreServiceProvider, the service providers of enabled modules and any other
- * service providers defined in $GLOBALS['conf']['container_service_providers'].
+ * \Drupal\Core\CoreServiceProvider, the service providers of enabled modules
+ * and any other service providers defined in
+ * $GLOBALS['conf']['container_service_providers'].
  *
  * This class exists only to support legacy code that cannot be dependency
  * injected. If your code needs it, consider refactoring it to be object
@@ -133,6 +134,13 @@ class Drupal {
    */
   const RECOMMENDED_PHP = '8.3.0';
 
+  /**
+   * Default location of gettext file on the translation server.
+   *
+   * @see locale_translation_default_translation_server()
+   */
+  const TRANSLATION_DEFAULT_SERVER_PATTERN = 'https://ftp.drupal.org/files/translations/%core/%project/%project-%version.%language.po';
+
   /**
    * The currently active container object, or NULL if not initialized yet.
    *
@@ -161,6 +169,7 @@ public static function unsetContainer() {
    * Returns the currently active global container.
    *
    * @return \Drupal\Component\DependencyInjection\ContainerInterface
+   *   The currently active global container.
    *
    * @throws \Drupal\Core\DependencyInjection\ContainerNotInitializedException
    */
@@ -175,6 +184,7 @@ public static function getContainer() {
    * Returns TRUE if the container has been initialized, FALSE otherwise.
    *
    * @return bool
+   *   TRUE if the container is initialized, FALSE otherwise.
    */
   public static function hasContainer() {
     return static::$container !== NULL;
@@ -215,6 +225,7 @@ public static function hasService($id) {
    * Gets the app root.
    *
    * @return string
+   *   The app root directory path.
    */
   public static function root() {
     return static::getContainer()->getParameter('app.root');
@@ -300,6 +311,7 @@ public static function routeMatch() {
    * @endcode
    *
    * @return \Drupal\Core\Session\AccountProxyInterface
+   *   The current user account proxy.
    */
   public static function currentUser() {
     return static::getContainer()->get('current_user');
@@ -385,6 +397,7 @@ public static function keyValueExpirable($collection) {
    * Returns the locking layer instance.
    *
    * @return \Drupal\Core\Lock\LockBackendInterface
+   *   The locking layer instance.
    *
    * @ingroup lock
    */
@@ -396,16 +409,14 @@ public static function lock() {
    * Retrieves a configuration object.
    *
    * This is the main entry point to the configuration API. Calling
-   * @code \Drupal::config('my_module.admin') @endcode will return a
-   * configuration object the my_module module can use to read its
-   * administrative settings.
+   * \Drupal::config('my_module.admin') will return a configuration object the
+   * my_module module can use to read its administrative settings.
    *
    * @param string $name
    *   The name of the configuration object to retrieve, which typically
    *   corresponds to a configuration file. For
-   *   @code \Drupal::config('my_module.admin') @endcode, the configuration
-   *   object returned will contain the content of the my_module.admin
-   *   configuration file.
+   *   \Drupal::config('my_module.admin'), the configuration object returned
+   *   will contain the content of the my_module.admin configuration file.
    *
    * @return \Drupal\Core\Config\ImmutableConfig
    *   An immutable configuration object.
@@ -461,6 +472,7 @@ public static function queue($name, $reliable = FALSE) {
    *   Name of the key/value collection to return.
    *
    * @return \Drupal\Core\KeyValueStore\KeyValueStoreInterface
+   *   The key/value storage collection for the specified name.
    */
   public static function keyValue($collection) {
     return static::getContainer()->get('keyvalue')->get($collection);
@@ -472,10 +484,12 @@ public static function keyValue($collection) {
    * Use this to store machine-generated data, local to a specific environment
    * that does not need deploying and does not need human editing; for example,
    * the last time cron was run. Data which needs to be edited by humans and
-   * needs to be the same across development, production, etc. environments
-   * (for example, the system maintenance message) should use \Drupal::config() instead.
+   * needs to be the same across development, production, etc. environments (for
+   * example, the system maintenance message) should use \Drupal::config()
+   * instead.
    *
    * @return \Drupal\Core\State\StateInterface
+   *   The state storage service.
    */
   public static function state() {
     return static::getContainer()->get('state');
@@ -529,6 +543,7 @@ public static function entityQueryAggregate($entity_type, $conjunction = 'AND')
    * Returns the flood instance.
    *
    * @return \Drupal\Core\Flood\FloodInterface
+   *   The flood instance.
    */
   public static function flood() {
     return static::getContainer()->get('flood');
@@ -538,6 +553,7 @@ public static function flood() {
    * Returns the module handler.
    *
    * @return \Drupal\Core\Extension\ModuleHandlerInterface
+   *   The module handler interface.
    */
   public static function moduleHandler() {
     return static::getContainer()->get('module_handler');
@@ -581,6 +597,7 @@ public static function urlGenerator() {
    * Returns the link generator service.
    *
    * @return \Drupal\Core\Utility\LinkGeneratorInterface
+   *   The link generator service.
    */
   public static function linkGenerator() {
     return static::getContainer()->get('link_generator');
@@ -609,10 +626,10 @@ public static function languageManager() {
   /**
    * Returns the CSRF token manager service.
    *
-   * The generated token is based on the session ID of the current user. Normally,
-   * anonymous users do not have a session, so the generated token will be
-   * different on every page request. To generate a token for users without a
-   * session, manually start a session prior to calling this function.
+   * The generated token is based on the session ID of the current user.
+   * Normally, anonymous users do not have a session, so the generated token
+   * will be different on every page request. To generate a token for users
+   * without a session, manually start a session prior to calling this function.
    *
    * @return \Drupal\Core\Access\CsrfTokenGenerator
    *   The CSRF token manager.
@@ -647,6 +664,7 @@ public static function formBuilder() {
    * Gets the theme service.
    *
    * @return \Drupal\Core\Theme\ThemeManagerInterface
+   *   The theme manager service.
    */
   public static function theme() {
     return static::getContainer()->get('theme.manager');
@@ -690,6 +708,7 @@ public static function menuTree() {
    * Returns the path validator.
    *
    * @return \Drupal\Core\Path\PathValidatorInterface
+   *   The path validator service.
    */
   public static function pathValidator() {
     return static::getContainer()->get('path.validator');

core/lib/Drupal/Component/Annotation/Plugin/Discovery/AnnotatedClassDiscovery.php

@@ -64,8 +64,8 @@ class AnnotatedClassDiscovery implements DiscoveryInterface {
    *   (optional) An array of namespace that may contain plugin implementations.
    *   Defaults to an empty array.
    * @param string $plugin_definition_annotation_name
-   *   (optional) The name of the annotation that contains the plugin definition.
-   *   Defaults to 'Drupal\Component\Annotation\Plugin'.
+   *   (optional) The name of the annotation that contains the plugin
+   *   definition. Defaults to 'Drupal\Component\Annotation\Plugin'.
    * @param string[] $annotation_namespaces
    *   (optional) Additional namespaces to be scanned for annotation classes.
    */
@@ -123,7 +123,8 @@ public function getDefinitions() {
             if ($fileinfo->getExtension() == 'php') {
               if ($cached = $this->fileCache->get($fileinfo->getPathName())) {
                 if (isset($cached['id'])) {
-                  // Explicitly unserialize this to create a new object instance.
+                  // Explicitly unserialize this to create a new object
+                  // instance.
                   $definitions[$cached['id']] = unserialize($cached['content']);
                 }
                 continue;

core/lib/Drupal/Component/Assertion/Inspector.php

@@ -94,7 +94,7 @@ public static function assertAllStringable($traversable) {
    * in any way will cause a problem.
    *
    * @param mixed $string
-   *   Variable to be examined
+   *   Variable to be examined.
    *
    * @return bool
    *   TRUE if $string is a string or an object castable to a string.
@@ -184,19 +184,16 @@ public static function assertAllStrictArrays($traversable) {
    *
    * @param mixed $traversable
    *   Variable to be examined.
-   * @param ...$keys
+   * @param string ...$keys
    *   Keys to be searched for.
    *
    * @return bool
    *   TRUE if $traversable can be traversed and all members have all keys.
    */
-  public static function assertAllHaveKey($traversable) {
-    $args = func_get_args();
-    unset($args[0]);
-
+  public static function assertAllHaveKey($traversable, string ...$keys) {
     if (is_iterable($traversable)) {
       foreach ($traversable as $member) {
-        foreach ($args as $key) {
+        foreach ($keys as $key) {
           if (!array_key_exists($key, $member)) {
             return FALSE;
           }
@@ -370,21 +367,18 @@ public static function assertAllRegularExpressionMatch($pattern, $traversable) {
    *
    * @param mixed $traversable
    *   Variable to be examined.
-   * @param ...$classes
+   * @param string ...$classes
    *   Classes and interfaces to test objects against.
    *
    * @return bool
    *   TRUE if $traversable can be traversed and all members are objects with
    *   at least one of the listed classes or interfaces.
    */
-  public static function assertAllObjects($traversable) {
-    $args = func_get_args();
-    unset($args[0]);
-
+  public static function assertAllObjects($traversable, string ...$classes) {
     if (is_iterable($traversable)) {
       foreach ($traversable as $member) {
-        if (count($args) > 0) {
-          foreach ($args as $instance) {
+        if (count($classes) > 0) {
+          foreach ($classes as $instance) {
             if ($member instanceof $instance) {
               // We're continuing to the next member on the outer loop.
               // @see http://php.net/continue

core/lib/Drupal/Component/Datetime/DateTimePlus.php

@@ -219,6 +219,7 @@ public static function createFromTimestamp($timestamp, $timezone = NULL, $settin
    *   to use things like negative years, which php's parser fails on, or
    *   any other specialized input with a known format. If provided the
    *   date will be created using the createFromFormat() method.
+   *   phpcs:ignore Drupal.Commenting.FunctionComment.ParamCommentFullStop
    *   @see http://php.net/manual/datetime.createfromformat.php
    * @param string $time
    *   String representing the time.
@@ -262,11 +263,11 @@ public static function createFromFormat($format, $time, $timezone = NULL, $setti
       $datetime_plus->setTimestamp($date->getTimestamp());
       $datetime_plus->setTimezone($date->getTimezone());
 
-      // Functions that parse date is forgiving, it might create a date that
-      // is not exactly a match for the provided value, so test for that by
-      // re-creating the date/time formatted string and comparing it to the input. For
-      // instance, an input value of '11' using a format of Y (4 digits) gets
-      // created as '0011' instead of '2011'.
+      // Functions that parse date is forgiving, it might create a date that is
+      // not exactly a match for the provided value, so test for that by
+      // re-creating the date/time formatted string and comparing it to the
+      // input. For instance, an input value of '11' using a format of Y (4
+      // digits) gets created as '0011' instead of '2011'.
       if ($settings['validate_format'] && $date->format($format) != $time) {
         throw new \UnexpectedValueException('The created date does not match the input value.');
       }
@@ -285,6 +286,7 @@ public static function createFromFormat($format, $time, $timezone = NULL, $setti
    *   parameter and the current timezone are ignored when the $time parameter
    *   either is a UNIX timestamp (e.g. @946684800) or specifies a timezone
    *   (e.g. 2010-01-28T15:00:00+02:00).
+   *   phpcs:ignore Drupal.Commenting.FunctionComment.ParamCommentFullStop
    *   @see http://php.net/manual/datetime.construct.php
    * @param array $settings
    *   (optional) Keyed array of settings. Defaults to empty array.

core/lib/Drupal/Component/FileCache/FileCacheFactory.php

@@ -39,7 +39,8 @@ class FileCacheFactory {
    *   The initialized FileCache object.
    */
   public static function get($collection, $default_configuration = []) {
-    // If there is a special key in the configuration, disable FileCache completely.
+    // If there is a special key in the configuration, disable FileCache
+    // completely.
     if (!empty(static::$configuration[static::DISABLE_CACHE])) {
       return new NullFileCache('', '');
     }

core/lib/Drupal/Component/FileSystem/FileSystem.php

@@ -37,8 +37,8 @@ public static function getOsTemporaryDirectory() {
 
     foreach ($directories as $directory) {
       if (is_dir($directory) && is_writable($directory)) {
-        // Both sys_get_temp_dir() and ini_get('upload_tmp_dir') can return paths
-        // with a trailing directory separator.
+        // Both sys_get_temp_dir() and ini_get('upload_tmp_dir') can return
+        // paths with a trailing directory separator.
         return rtrim($directory, DIRECTORY_SEPARATOR);
       }
     }

core/lib/Drupal/Component/Gettext/PoHeader.php

@@ -277,7 +277,25 @@ private function parseHeader($header) {
    */
   private function parseArithmetic($string) {
     // Operator precedence table.
-    $precedence = ["(" => -1, ")" => -1, "?" => 1, ":" => 1, "||" => 3, "&&" => 4, "==" => 5, "!=" => 5, "<" => 6, ">" => 6, "<=" => 6, ">=" => 6, "+" => 7, "-" => 7, "*" => 8, "/" => 8, "%" => 8];
+    $precedence = [
+      "(" => -1,
+      ")" => -1,
+      "?" => 1,
+      ":" => 1,
+      "||" => 3,
+      "&&" => 4,
+      "==" => 5,
+      "!=" => 5,
+      "<" => 6,
+      ">" => 6,
+      "<=" => 6,
+      ">=" => 6,
+      "+" => 7,
+      "-" => 7,
+      "*" => 8,
+      "/" => 8,
+      "%" => 8,
+    ];
     // Right associativity.
     $right_associativity = ["?" => 1, ":" => 1];
 
@@ -440,20 +458,24 @@ private function tokenizeFormula($formula) {
    * An example of plural formula parting and evaluation:
    *   Plural formula: 'n!=1'
    * This formula is parsed by parseArithmetic() to a stack (array) of elements:
-   *   array(
+   * @code
+   *   [
    *     0 => '$n',
    *     1 => '1',
    *     2 => '!=',
-   *   );
+   *   ];
+   * @endcode
    * The evaluatePlural() method evaluates the $element_stack using the plural
    * value $n. Before the actual evaluation, the '$n' in the array is replaced
    * by the value of $n.
    *   For example: $n = 2 results in:
-   *   array(
+   * @code
+   *   [
    *     0 => '2',
    *     1 => '1',
    *     2 => '!=',
-   *   );
+   *   ]
+   * @endcode
    * The stack is processed until only one element is (the result) is left. In
    * every iteration the top elements of the stack, up until the first operator,
    * are evaluated. After evaluation the arguments and the operator itself are
@@ -462,9 +484,11 @@ private function tokenizeFormula($formula) {
    *   Because the operator is '!=' the example stack is evaluated as:
    *   $f = (int) 2 != 1;
    *   The resulting stack is:
-   *   array(
+   * @code
+   *   [
    *     0 => 1,
-   *   );
+   *   ]
+   * @endcode
    * With only one element left in the stack (the final result) the loop is
    * terminated and the result is returned.
    *

core/lib/Drupal/Component/Gettext/PoMemoryWriter.php

@@ -67,6 +67,7 @@ public function setLangcode($langcode) {
    * Not implemented. Not relevant for the MemoryWriter.
    */
   public function getLangcode() {
+    throw new \LogicException(__METHOD__ . '() not implemented. Not relevant for the MemoryWriter');
   }
 
   /**

core/lib/Drupal/Component/Gettext/PoStreamReader.php

@@ -337,7 +337,8 @@ private function readLine() {
           $this->currentItem = [];
         }
         elseif ($this->context == 'MSGID') {
-          // We are currently already in the context, meaning we passed an id with no data.
+          // We are currently already in the context, meaning we passed an id
+          // with no data.
           $this->errors[] = new FormattableMarkup('The translation stream %uri contains an error: "msgid" is unexpected on line %line.', $log_vars);
           return FALSE;
         }
@@ -455,7 +456,8 @@ private function readLine() {
         return;
       }
       elseif ($line != '') {
-        // Anything that is not a token may be a continuation of a previous token.
+        // Anything that is not a token may be a continuation of a previous
+        // token.
 
         $quoted = $this->parseQuoted($line);
         if ($quoted === FALSE) {

core/lib/Drupal/Component/Graph/Graph.php

@@ -9,6 +9,8 @@ class Graph {
 
   /**
    * Holds the directed acyclic graph.
+   *
+   * @var array
    */
   protected $graph;
 
@@ -50,8 +52,8 @@ public function __construct($graph) {
    *     this vertex.
    *   - 'reverse_paths': Contains a list of vertices that has a path from them
    *     to this vertex.
-   *   - 'weight': If there is a path from a vertex to another then the weight of
-   *     the latter is higher.
+   *   - 'weight': If there is a path from a vertex to another then the weight
+   *      of the latter is higher.
    *   - 'component': Vertices in the same component have the same component
    *     identifier.
    */
@@ -99,7 +101,8 @@ public function searchAndSort() {
    * @see \Drupal\Component\Graph\Graph::searchAndSort()
    */
   protected function depthFirstSearch(&$state, $start, &$component = NULL) {
-    // Assign new component for each new vertex, i.e. when not called recursively.
+    // Assign new component for each new vertex, i.e. when not called
+    // recursively.
     if (!isset($component)) {
       $component = $start;
     }

core/lib/Drupal/Component/PhpStorage/FileReadOnlyStorage.php

@@ -18,7 +18,8 @@ class FileReadOnlyStorage implements PhpStorageInterface {
    * Constructs this FileStorage object.
    *
    * @param string[] $configuration
-   *   An associative array, containing at least two keys (the rest are ignored):
+   *   An associative array, containing at least two keys (the rest are
+   *   ignored):
    *   - directory: The directory where the files should be stored.
    *   - bin: The storage bin. Multiple storage objects can be instantiated with
    *   the same configuration, but for different bins.

core/lib/Drupal/Component/Plugin/Discovery/AttributeClassDiscovery.php

@@ -71,7 +71,8 @@ public function getDefinitions() {
             if ($fileinfo->getExtension() === 'php') {
               if ($cached = $this->fileCache->get($fileinfo->getPathName())) {
                 if (isset($cached['id'])) {
-                  // Explicitly unserialize this to create a new object instance.
+                  // Explicitly unserialize this to create a new object
+                  // instance.
                   $definitions[$cached['id']] = unserialize($cached['content']);
                 }
                 continue;

core/lib/Drupal/Component/Plugin/Discovery/DiscoveryCachedTrait.php

@@ -2,6 +2,9 @@
 
 namespace Drupal\Component\Plugin\Discovery;
 
+/**
+ * Trait for accessing cached definitions of the plugin discovery component.
+ */
 trait DiscoveryCachedTrait {
 
   use DiscoveryTrait;

core/lib/Drupal/Component/Plugin/Discovery/StaticDiscoveryDecorator.php

@@ -22,7 +22,7 @@ class StaticDiscoveryDecorator extends StaticDiscovery {
   protected $registerDefinitions;
 
   /**
-   * Constructs a \Drupal\Component\Plugin\Discovery\StaticDiscoveryDecorator object.
+   * Constructs StaticDiscoveryDecorator object.
    *
    * @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated
    *   The discovery object that is being decorated.

core/lib/Drupal/Component/Plugin/Exception/InvalidPluginDefinitionException.php

@@ -23,12 +23,12 @@ class InvalidPluginDefinitionException extends PluginException {
    *   The exception message.
    * @param int $code
    *   The exception code.
-   * @param \Exception|null $previous
+   * @param \Throwable|null $previous
    *   The previous throwable used for exception chaining.
    *
    * @see \Exception
    */
-  public function __construct($plugin_id, $message = '', $code = 0, ?\Exception $previous = NULL) {
+  public function __construct($plugin_id, $message = '', $code = 0, ?\Throwable $previous = NULL) {
     $this->pluginId = $plugin_id;
     parent::__construct($message, $code, $previous);
   }

core/lib/Drupal/Component/Plugin/Exception/PluginNotFoundException.php

@@ -16,12 +16,12 @@ class PluginNotFoundException extends PluginException {
    *   The exception message.
    * @param int $code
    *   The exception code.
-   * @param \Exception|null $previous
+   * @param \Throwable|null $previous
    *   The previous throwable used for exception chaining.
    *
    * @see \Exception
    */
-  public function __construct($plugin_id, $message = '', $code = 0, ?\Exception $previous = NULL) {
+  public function __construct($plugin_id, $message = '', $code = 0, ?\Throwable $previous = NULL) {
     if (empty($message)) {
       $message = sprintf("Plugin ID '%s' was not found.", $plugin_id);
     }

core/lib/Drupal/Component/Plugin/Factory/DefaultFactory.php

@@ -17,7 +17,7 @@
 class DefaultFactory implements FactoryInterface {
 
   /**
-   * The object that retrieves the definitions of the plugins that this factory instantiates.
+   * The object that gets the plugin definitions that this factory instantiates.
    *
    * The plugin definition includes the plugin class and possibly other
    * information necessary for proper instantiation.

core/lib/Drupal/Component/Plugin/Factory/ReflectionFactory.php

@@ -32,7 +32,7 @@ public function createInstance($plugin_id, array $configuration = []) {
   }
 
   /**
-   * Inspects the plugin class and build a list of arguments for the constructor.
+   * Inspects the plugin class and builds a list of constructor arguments.
    *
    * This is provided as a helper method so factories extending this class can
    * replace this and insert their own reflection logic.

core/lib/Drupal/Component/Plugin/PluginManagerBase.php

@@ -27,7 +27,7 @@ abstract class PluginManagerBase implements PluginManagerInterface {
   protected $factory;
 
   /**
-   * The object that returns the preconfigured plugin instance appropriate for a particular runtime condition.
+   * The preconfigured plugin instance for a particular runtime condition.
    *
    * @var \Drupal\Component\Plugin\Mapper\MapperInterface|null
    */

core/lib/Drupal/Component/Utility/DeprecationHelper.php

@@ -18,9 +18,6 @@ final class DeprecationHelper {
    * The below templates help code editors and PHPStan understand the return
    * value of this function.
    *
-   * @template Current
-   * @template Deprecated
-   *
    * @param string $currentVersion
    *   Version to check against.
    * @param string $deprecatedVersion
@@ -35,10 +32,14 @@ final class DeprecationHelper {
    *   deprecation. The current callback when the current version is greater
    *   than or equal to the version of the deprecation. Otherwise, the
    *   deprecated callback.
+   *
+   * @template Current
+   * @template Deprecated
    */
   public static function backwardsCompatibleCall(string $currentVersion, string $deprecatedVersion, callable $currentCallable, callable $deprecatedCallable): mixed {
-    // Normalize the version string when it's a dev version to the first point release of that minor. E.g. 10.2.x-dev
-    // and 10.2-dev both translate to 10.2.0
+    // Normalize the version string when it's a dev version to the first point
+    // release of that minor. E.g. 10.2.x-dev and 10.2-dev both translate to
+    // 10.2.0
     $normalizedVersion = str_ends_with($currentVersion, '-dev') ? str_replace(['.x-dev', '-dev'], '.0', $currentVersion) : $currentVersion;
 
     return version_compare($normalizedVersion, $deprecatedVersion, '>=') ? $currentCallable() : $deprecatedCallable();