Merge remote-tracking branch 'upstream/develop' into 4.5

system/Pager/PagerRenderer.php

@@ -25,14 +25,14 @@
 class PagerRenderer
 {
     /**
-     * First page number.
+     * First page number in the set of links to be displayed.
      *
      * @var int
      */
     protected $first;
 
     /**
-     * Last page number.
+     * Last page number in the set of links to be displayed.
      *
      * @var int
      */
@@ -85,8 +85,11 @@ class PagerRenderer
      */
     public function __construct(array $details)
     {
-        $this->first        = 1;
-        $this->last         = $details['pageCount'];
+        // `first` and `last` will be updated by `setSurroundCount()`.
+        // You must call `setSurroundCount()` after instantiation.
+        $this->first = 1;
+        $this->last  = $details['pageCount'];
+
         $this->current      = $details['currentPage'];
         $this->total        = $details['total'];
         $this->uri          = $details['uri'];
@@ -122,8 +125,6 @@ public function hasPrevious(): bool
      * page before the current page, but is the page just before the
      * "first" page.
      *
-     * You MUST call hasPrevious() first, or this value may be invalid.
-     *
      * @return string|null
      */
     public function getPrevious()
@@ -162,8 +163,6 @@ public function hasNext(): bool
      * page after the current page, but is the page that follows the
      * "last" page.
      *
-     * You MUST call hasNext() first, or this value may be invalid.
-     *
      * @return string|null
      */
     public function getNext()
@@ -260,6 +259,8 @@ public function getCurrent(): string
      * is represented by another array containing of the URI the link
      * should go to, the title (number) of the link, and a boolean
      * value representing whether this link is active or not.
+     *
+     * @return list<array{uri:string, title:int, active:bool}>
      */
     public function links(): array
     {
@@ -381,7 +382,7 @@ public function getNextPage()
     }
 
     /**
-     * Returns the page number of the first page.
+     * Returns the page number of the first page in the set of links to be displayed.
      */
     public function getFirstPageNumber(): int
     {
@@ -397,7 +398,7 @@ public function getCurrentPageNumber(): int
     }
 
     /**
-     * Returns the page number of the last page.
+     * Returns the page number of the last page in the set of links to be displayed.
      */
     public function getLastPageNumber(): int
     {

system/ThirdParty/Kint/CallFinder.php

@@ -138,7 +138,7 @@ class CallFinder
     /**
      * @psalm-param callable-array|callable-string $function
      *
-     * @param mixed $function
+     * @psalm-return list<array{parameters: list, modifiers: list<PhpToken>}>
      *
      * @return array List of matching calls on the relevant line
      */
@@ -187,6 +187,7 @@ public static function getFunctionCalls(string $source, int $line, $function): a
             $identifier[T_NAME_RELATIVE] = true;
         }
 
+        /** @psalm-var list<PhpToken> */
         $tokens = \token_get_all($source);
         $cursor = 1;
         $function_calls = [];
@@ -449,8 +450,6 @@ private static function realTokenIndex(array $tokens, int $index): ?int
      * for `$token[0]` then "..." will incorrectly match the "." operator.
      *
      * @psalm-param PhpToken $token The token to check
-     *
-     * @param mixed $token
      */
     private static function tokenIsOperator($token): bool
     {

system/ThirdParty/Kint/Kint.php

@@ -133,7 +133,7 @@ class Kint implements FacadeInterface
     public static $aliases = [
         ['Kint\\Kint', 'dump'],
         ['Kint\\Kint', 'trace'],
-        ['Kint\\Kint', 'dumpArray'],
+        ['Kint\\Kint', 'dumpAll'],
     ];
 
     /**
@@ -537,7 +537,7 @@ public static function trace()
      *
      * Functionally equivalent to Kint::dump(1) or Kint::dump(debug_backtrace())
      *
-     * @param mixed ...$args
+     * @psalm-param array ...$args
      *
      * @return int|string
      */
@@ -599,6 +599,7 @@ public static function shortenPath(string $file): string
         $match = '/';
 
         foreach (static::$app_root_dirs as $path => $alias) {
+            /** @psalm-var string $path */
             if (empty($path)) {
                 continue;
             }

system/ThirdParty/Kint/Parser/BlacklistPlugin.php

@@ -29,6 +29,7 @@
 
 use Kint\Zval\InstanceValue;
 use Kint\Zval\Value;
+use Psr\Container\ContainerInterface;
 
 class BlacklistPlugin extends AbstractPlugin
 {
@@ -44,7 +45,7 @@ class BlacklistPlugin extends AbstractPlugin
      *
      * @var array
      */
-    public static $shallow_blacklist = ['Psr\\Container\\ContainerInterface'];
+    public static $shallow_blacklist = [ContainerInterface::class];
 
     public function getTypes(): array
     {

system/ThirdParty/Kint/Parser/ClosurePlugin.php

@@ -67,7 +67,7 @@ public function parse(&$var, Value &$o, int $trigger): void
         }
 
         $p = new Representation('Parameters');
-        $p->contents = &$o->parameters;
+        $p->contents = $o->parameters;
         $o->addRepresentation($p, 0);
 
         $statics = [];

system/ThirdParty/Kint/Parser/Parser.php

@@ -72,7 +72,7 @@ class Parser
      * @param int     $depth_limit Maximum depth to parse data
      * @param ?string $caller      Caller class name
      */
-    public function __construct(int $depth_limit = 0, ?string $caller = null)
+    public function __construct(int $depth_limit = 0, string $caller = null)
     {
         $this->marker = "kint\0".\random_bytes(16);
 
@@ -83,7 +83,7 @@ public function __construct(int $depth_limit = 0, ?string $caller = null)
     /**
      * Set the caller class.
      */
-    public function setCallerClass(?string $caller = null): void
+    public function setCallerClass(string $caller = null): void
     {
         $this->noRecurseCall();
 

system/ThirdParty/Kint/Parser/PluginInterface.php

@@ -38,7 +38,7 @@ public function getTypes(): array;
     public function getTriggers(): int;
 
     /**
-     * @param mixed &$var
+     * @psalm-param mixed &$var
      */
     public function parse(&$var, Value &$o, int $trigger): void;
 }

system/ThirdParty/Kint/Parser/TablePlugin.php

@@ -30,6 +30,12 @@
 use Kint\Zval\Representation\Representation;
 use Kint\Zval\Value;
 
+// Note: Interaction with ArrayLimitPlugin:
+// Any array limited children will be shown in tables identically to
+// non-array-limited children since the table only shows that it is an array
+// and it's size anyway. Because ArrayLimitPlugin halts the parse on finding
+// a limit all other plugins including this one are stopped, so you cannot get
+// a tabular representation of an array that is longer than the limit.
 class TablePlugin extends AbstractPlugin
 {
     public function getTypes(): array

system/ThirdParty/Kint/Renderer/RichRenderer.php

@@ -140,6 +140,13 @@ class RichRenderer extends AbstractRenderer
      */
     public static $sort = self::SORT_NONE;
 
+    /**
+     * Timestamp to print in footer in date() format.
+     *
+     * @var ?string
+     */
+    public static $timestamp = null;
+
     public static $needs_pre_render = true;
     public static $needs_folder_render = true;
 
@@ -465,29 +472,7 @@ public function postRender(): string
             $output .= '<nav></nav>';
         }
 
-        if (isset($this->call_info['callee']['file'])) {
-            $output .= 'Called from '.$this->ideLink(
-                $this->call_info['callee']['file'],
-                $this->call_info['callee']['line']
-            );
-        }
-
-        if (
-            isset($this->call_info['callee']['function']) &&
-            (
-                !empty($this->call_info['callee']['class']) ||
-                !\in_array(
-                    $this->call_info['callee']['function'],
-                    ['include', 'include_once', 'require', 'require_once'],
-                    true
-                )
-            )
-        ) {
-            $output .= ' [';
-            $output .= $this->call_info['callee']['class'] ?? '';
-            $output .= $this->call_info['callee']['type'] ?? '';
-            $output .= $this->call_info['callee']['function'].'()]';
-        }
+        $output .= $this->calledFrom();
 
         if (!empty($this->call_info['trace']) && \count($this->call_info['trace']) > 1) {
             $output .= '<ol>';
@@ -497,8 +482,8 @@ public function postRender(): string
                 }
 
                 $output .= '<li>'.$this->ideLink($step['file'], $step['line']); // closing tag not required
-                if (isset($step['function'])
-                    && !\in_array($step['function'], ['include', 'include_once', 'require', 'require_once'], true)
+                if (isset($step['function']) &&
+                    !\in_array($step['function'], ['include', 'include_once', 'require', 'require_once'], true)
                 ) {
                     $output .= ' [';
                     $output .= $step['class'] ?? '';
@@ -516,8 +501,6 @@ public function postRender(): string
 
     /**
      * @psalm-param Encoding $encoding
-     *
-     * @param mixed $encoding
      */
     public function escape(string $string, $encoding = false): string
     {
@@ -559,6 +542,45 @@ public function ideLink(string $file, int $line): string
         return '<a '.$class.'href="'.$this->escape($ideLink).'">'.$path.'</a>';
     }
 
+    protected function calledFrom(): string
+    {
+        $output = '';
+
+        if (isset($this->call_info['callee']['file'])) {
+            $output .= ' '.$this->ideLink(
+                $this->call_info['callee']['file'],
+                $this->call_info['callee']['line']
+            );
+        }
+
+        if (
+            isset($this->call_info['callee']['function']) &&
+            (
+                !empty($this->call_info['callee']['class']) ||
+                !\in_array(
+                    $this->call_info['callee']['function'],
+                    ['include', 'include_once', 'require', 'require_once'],
+                    true
+                )
+            )
+        ) {
+            $output .= ' [';
+            $output .= $this->call_info['callee']['class'] ?? '';
+            $output .= $this->call_info['callee']['type'] ?? '';
+            $output .= $this->call_info['callee']['function'].'()]';
+        }
+
+        if ('' !== $output) {
+            $output = 'Called from'.$output;
+        }
+
+        if (null !== self::$timestamp) {
+            $output .= ' '.\date(self::$timestamp);
+        }
+
+        return $output;
+    }
+
     protected function renderTab(Value $o, Representation $rep): string
     {
         if (($plugin = $this->getPlugin(self::$tab_plugins, $rep->hints)) && $plugin instanceof TabPluginInterface) {

system/ThirdParty/Kint/Renderer/Text/AbstractPlugin.php

@@ -42,7 +42,7 @@ public function __construct(TextRenderer $r)
         $this->renderer = $r;
     }
 
-    public function renderLockedHeader(Value $o, ?string $content = null): string
+    public function renderLockedHeader(Value $o, string $content = null): string
     {
         $out = '';
 

system/ThirdParty/Kint/Renderer/TextRenderer.php

@@ -108,6 +108,13 @@ class TextRenderer extends AbstractRenderer
      */
     public static $sort = self::SORT_NONE;
 
+    /**
+     * Timestamp to print in footer in date() format.
+     *
+     * @var ?string
+     */
+    public static $timestamp = null;
+
     public $header_width = 80;
     public $indent_width = 4;
 
@@ -300,7 +307,7 @@ public function filterParserPlugins(array $plugins): array
     {
         $return = [];
 
-        foreach ($plugins as $index => $plugin) {
+        foreach ($plugins as $plugin) {
             foreach (self::$parser_plugin_whitelist as $whitelist) {
                 if ($plugin instanceof $whitelist) {
                     $return[] = $plugin;
@@ -319,8 +326,6 @@ public function ideLink(string $file, int $line): string
 
     /**
      * @psalm-param Encoding $encoding
-     *
-     * @param mixed $encoding
      */
     public function escape(string $string, $encoding = false): string
     {
@@ -355,6 +360,13 @@ protected function calledFrom(): string
             $output .= $this->call_info['callee']['function'].'()]';
         }
 
+        if (null !== self::$timestamp) {
+            if (\strlen($output)) {
+                $output .= ' ';
+            }
+            $output .= \date(self::$timestamp);
+        }
+
         return $output;
     }
 

system/ThirdParty/Kint/Utils.php

@@ -255,8 +255,6 @@ public static function normalizeAliases(array &$aliases): void
 
     /**
      * @psalm-param Encoding $encoding
-     *
-     * @param mixed $encoding
      */
     public static function truncateString(string $input, int $length = PHP_INT_MAX, string $end = '...', $encoding = false): string
     {

system/ThirdParty/Kint/Zval/BlobValue.php

@@ -122,8 +122,6 @@ public function transplant(Value $old): void
 
     /**
      * @psalm-param Encoding $encoding
-     *
-     * @param mixed $encoding
      */
     public static function strlen(string $string, $encoding = false): int
     {
@@ -142,10 +140,8 @@ public static function strlen(string $string, $encoding = false): int
 
     /**
      * @psalm-param Encoding $encoding
-     *
-     * @param mixed $encoding
      */
-    public static function substr(string $string, int $start, ?int $length = null, $encoding = false): string
+    public static function substr(string $string, int $start, int $length = null, $encoding = false): string
     {
         if (\function_exists('mb_substr')) {
             if (false === $encoding) {