package and depencies

vendor/doctrine/lexer/UPGRADE.md

@@ -0,0 +1,14 @@
+Note about upgrading: Doctrine uses static and runtime mechanisms to raise
+awareness about deprecated code.
+
+- Use of `@deprecated` docblock that is detected by IDEs (like PHPStorm) or
+  Static Analysis tools (like Psalm, phpstan)
+- Use of our low-overhead runtime deprecation API, details:
+  https://github.com/doctrine/deprecations/
+
+# Upgrade to 2.0.0
+
+`AbstractLexer::glimpse()` and `AbstractLexer::peek()` now return
+instances of `Doctrine\Common\Lexer\Token`, which is an array-like class
+Using it as an array is deprecated in favor of using properties of that class.
+Using `count()` on it is deprecated with no replacement.

vendor/doctrine/lexer/composer.json

@@ -1,7 +1,8 @@
 {
     "name": "doctrine/lexer",
-    "type": "library",
     "description": "PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.",
+    "license": "MIT",
+    "type": "library",
     "keywords": [
         "php",
         "parser",
@@ -9,27 +10,41 @@
         "annotations",
         "docblock"
     ],
-    "homepage": "https://www.doctrine-project.org/projects/lexer.html",
-    "license": "MIT",
     "authors": [
-        {"name": "Guilherme Blanco", "email": "guilhermeblanco@gmail.com"},
-        {"name": "Roman Borschel", "email": "roman@code-factory.org"},
-        {"name": "Johannes Schmitt", "email": "schmittjoh@gmail.com"}
+        {
+            "name": "Guilherme Blanco",
+            "email": "guilhermeblanco@gmail.com"
+        },
+        {
+            "name": "Roman Borschel",
+            "email": "roman@code-factory.org"
+        },
+        {
+            "name": "Johannes Schmitt",
+            "email": "schmittjoh@gmail.com"
+        }
     ],
+    "homepage": "https://www.doctrine-project.org/projects/lexer.html",
     "require": {
-        "php": "^7.1 || ^8.0"
+        "php": "^7.1 || ^8.0",
+        "doctrine/deprecations": "^1.0"
     },
     "require-dev": {
-        "doctrine/coding-standard": "^9.0",
+        "doctrine/coding-standard": "^9 || ^10",
         "phpstan/phpstan": "^1.3",
         "phpunit/phpunit": "^7.5 || ^8.5 || ^9.5",
-        "vimeo/psalm": "^4.11"
+        "psalm/plugin-phpunit": "^0.18.3",
+        "vimeo/psalm": "^4.11 || ^5.0"
     },
     "autoload": {
-        "psr-4": { "Doctrine\\Common\\Lexer\\": "lib/Doctrine/Common/Lexer" }
+        "psr-4": {
+            "Doctrine\\Common\\Lexer\\": "src"
+        }
     },
     "autoload-dev": {
-        "psr-4": { "Doctrine\\Tests\\": "tests/Doctrine" }
+        "psr-4": {
+            "Doctrine\\Tests\\Common\\Lexer\\": "tests"
+        }
     },
     "config": {
         "allow-plugins": {

vendor/doctrine/lexer/psalm.xml

@@ -1,15 +0,0 @@
-<?xml version="1.0"?>
-<psalm
-    errorLevel="5"
-    resolveFromConfigFile="true"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xmlns="https://getpsalm.org/schema/config"
-    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
->
-    <projectFiles>
-        <directory name="lib/Doctrine/Common/Lexer" />
-        <ignoreFiles>
-            <directory name="vendor" />
-        </ignoreFiles>
-    </projectFiles>
-</psalm>

vendor/doctrine/lexer/src/AbstractLexer.php

@@ -5,9 +5,10 @@ declare(strict_types=1);
 namespace Doctrine\Common\Lexer;
 
 use ReflectionClass;
+use UnitEnum;
 
+use function get_class;
 use function implode;
-use function in_array;
 use function preg_split;
 use function sprintf;
 use function substr;
@@ -19,7 +20,8 @@ use const PREG_SPLIT_OFFSET_CAPTURE;
 /**
  * Base class for writing simple lexers, i.e. for creating small DSLs.
  *
- * @psalm-type Token = array{value: int|string, type:string|int|null, position:int}
+ * @template T of UnitEnum|string|int
+ * @template V of string|int
  */
 abstract class AbstractLexer
 {
@@ -33,14 +35,7 @@ abstract class AbstractLexer
     /**
      * Array of scanned tokens.
      *
-     * Each token is an associative array containing three items:
-     *  - 'value'    : the string value of the token in the input string
-     *  - 'type'     : the type of the token (identifier, numeric, string, input
-     *                 parameter, none)
-     *  - 'position' : the position of the token in the input string
-     *
-     * @var mixed[][]
-     * @psalm-var list<Token>
+     * @var list<Token<T, V>>
      */
     private $tokens = [];
 
@@ -62,7 +57,7 @@ abstract class AbstractLexer
      * The next token in the input.
      *
      * @var mixed[]|null
-     * @psalm-var Token|null
+     * @psalm-var Token<T, V>|null
      */
     public $lookahead;
 
@@ -70,7 +65,7 @@ abstract class AbstractLexer
      * The last matched/seen token.
      *
      * @var mixed[]|null
-     * @psalm-var Token|null
+     * @psalm-var Token<T, V>|null
      */
     public $token;
 
@@ -150,31 +145,37 @@ abstract class AbstractLexer
     /**
      * Checks whether a given token matches the current lookahead.
      *
-     * @param int|string $type
+     * @param T $type
      *
      * @return bool
+     *
+     * @psalm-assert-if-true !=null $this->lookahead
      */
     public function isNextToken($type)
     {
-        return $this->lookahead !== null && $this->lookahead['type'] === $type;
+        return $this->lookahead !== null && $this->lookahead->isA($type);
     }
 
     /**
      * Checks whether any of the given tokens matches the current lookahead.
      *
-     * @param list<int|string> $types
+     * @param list<T> $types
      *
      * @return bool
+     *
+     * @psalm-assert-if-true !=null $this->lookahead
      */
     public function isNextTokenAny(array $types)
     {
-        return $this->lookahead !== null && in_array($this->lookahead['type'], $types, true);
+        return $this->lookahead !== null && $this->lookahead->isA(...$types);
     }
 
     /**
      * Moves to the next token in the input string.
      *
      * @return bool
+     *
+     * @psalm-assert-if-true !null $this->lookahead
      */
     public function moveNext()
     {
@@ -189,13 +190,13 @@ abstract class AbstractLexer
     /**
      * Tells the lexer to skip input tokens until it sees a token with the given value.
      *
-     * @param string $type The token type to skip until.
+     * @param T $type The token type to skip until.
      *
      * @return void
      */
     public function skipUntil($type)
     {
-        while ($this->lookahead !== null && $this->lookahead['type'] !== $type) {
+        while ($this->lookahead !== null && ! $this->lookahead->isA($type)) {
             $this->moveNext();
         }
     }
@@ -203,7 +204,7 @@ abstract class AbstractLexer
     /**
      * Checks if given value is identical to the given token.
      *
-     * @param mixed      $value
+     * @param string     $value
      * @param int|string $token
      *
      * @return bool
@@ -217,7 +218,7 @@ abstract class AbstractLexer
      * Moves the lookahead token forward.
      *
      * @return mixed[]|null The next token or NULL if there are no more tokens ahead.
-     * @psalm-return Token|null
+     * @psalm-return Token<T, V>|null
      */
     public function peek()
     {
@@ -232,7 +233,7 @@ abstract class AbstractLexer
      * Peeks at the next token, returns it and immediately resets the peek.
      *
      * @return mixed[]|null The next token or NULL if there are no more tokens ahead.
-     * @psalm-return Token|null
+     * @psalm-return Token<T, V>|null
      */
     public function glimpse()
     {
@@ -270,26 +271,32 @@ abstract class AbstractLexer
 
         foreach ($matches as $match) {
             // Must remain before 'value' assignment since it can change content
-            $type = $this->getType($match[0]);
+            $firstMatch = $match[0];
+            $type       = $this->getType($firstMatch);
 
-            $this->tokens[] = [
-                'value' => $match[0],
-                'type'  => $type,
-                'position' => $match[1],
-            ];
+            $this->tokens[] = new Token(
+                $firstMatch,
+                $type,
+                $match[1]
+            );
         }
     }
 
     /**
      * Gets the literal for a given token.
      *
-     * @param int|string $token
+     * @param T $token
      *
      * @return int|string
      */
     public function getLiteral($token)
     {
+        if ($token instanceof UnitEnum) {
+            return get_class($token) . '::' . $token->name;
+        }
+
         $className = static::class;
+
         $reflClass = new ReflectionClass($className);
         $constants = $reflClass->getConstants();
 
@@ -331,7 +338,9 @@ abstract class AbstractLexer
      *
      * @param string $value
      *
-     * @return int|string|null
+     * @return T|null
+     *
+     * @param-out V $value
      */
     abstract protected function getType(&$value);
 }

vendor/doctrine/lexer/src/Token.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Common\Lexer;
+
+use ArrayAccess;
+use Doctrine\Deprecations\Deprecation;
+use ReturnTypeWillChange;
+use UnitEnum;
+
+use function in_array;
+
+/**
+ * @template T of UnitEnum|string|int
+ * @template V of string|int
+ * @implements ArrayAccess<string,mixed>
+ */
+final class Token implements ArrayAccess
+{
+    /**
+     * The string value of the token in the input string
+     *
+     * @readonly
+     * @var V
+     */
+    public $value;
+
+    /**
+     * The type of the token (identifier, numeric, string, input parameter, none)
+     *
+     * @readonly
+     * @var T|null
+     */
+    public $type;
+
+    /**
+     * The position of the token in the input string
+     *
+     * @readonly
+     * @var int
+     */
+    public $position;
+
+    /**
+     * @param V      $value
+     * @param T|null $type
+     */
+    public function __construct($value, $type, int $position)
+    {
+        $this->value    = $value;
+        $this->type     = $type;
+        $this->position = $position;
+    }
+
+    /** @param T ...$types */
+    public function isA(...$types): bool
+    {
+        return in_array($this->type, $types, true);
+    }
+
+    /**
+     * @deprecated Use the value, type or position property instead
+     * {@inheritDoc}
+     */
+    public function offsetExists($offset): bool
+    {
+        Deprecation::trigger(
+            'doctrine/lexer',
+            'https://github.com/doctrine/lexer/pull/79',
+            'Accessing %s properties via ArrayAccess is deprecated, use the value, type or position property instead',
+            self::class
+        );
+
+        return in_array($offset, ['value', 'type', 'position'], true);
+    }
+
+    /**
+     * @deprecated Use the value, type or position property instead
+     * {@inheritDoc}
+     *
+     * @param O $offset
+     *
+     * @return mixed
+     * @psalm-return (
+     *     O is 'value'
+     *     ? V
+     *     : (
+     *         O is 'type'
+     *         ? T|null
+     *         : (
+     *             O is 'position'
+     *             ? int
+     *             : mixed
+     *         )
+     *     )
+     * )
+     *
+     * @template O of array-key
+     */
+    #[ReturnTypeWillChange]
+    public function offsetGet($offset)
+    {
+        Deprecation::trigger(
+            'doctrine/lexer',
+            'https://github.com/doctrine/lexer/pull/79',
+            'Accessing %s properties via ArrayAccess is deprecated, use the value, type or position property instead',
+            self::class
+        );
+
+        return $this->$offset;
+    }
+
+    /**
+     * @deprecated no replacement planned
+     * {@inheritDoc}
+     */
+    public function offsetSet($offset, $value): void
+    {
+        Deprecation::trigger(
+            'doctrine/lexer',
+            'https://github.com/doctrine/lexer/pull/79',
+            'Setting %s properties via ArrayAccess is deprecated',
+            self::class
+        );
+
+        $this->$offset = $value;
+    }
+
+    /**
+     * @deprecated no replacement planned
+     * {@inheritDoc}
+     */
+    public function offsetUnset($offset): void
+    {
+        Deprecation::trigger(
+            'doctrine/lexer',
+            'https://github.com/doctrine/lexer/pull/79',
+            'Setting %s properties via ArrayAccess is deprecated',
+            self::class
+        );
+
+        $this->$offset = null;
+    }
+}