Merge pull request #307 from phpDocumentor/feature/expressions-in-arguments

Started reworking expression strings into Expression objects

Author: jaapio

docs/expressions.rst

@@ -0,0 +1,60 @@
+Expressions
+===========
+
+Starting with version 5.4, we now support parsing expressions and extracting types and references to elements from them.
+
+.. info::
+
+   An expression is, for example, the default value for a property or argument, the definition of an enum case or a
+   constant value. These are called expressions and can contain more complex combinations of operators and values.
+
+As this library revolves around reflecting Static information, most parts of an expression are considered irrelevant;
+except for type information -such as type hints- and references to other elements, such as constants. As such, whenever
+an expression is interpreted, it will result in a string containing placeholders and an array containing the reflected
+parts -such as FQSENs-.
+
+This means that the getters like ``getDefault()`` will return a string or when you provide the optional argument
+$isString as being false, it will return an Expression object; which, when cast to string, will provide the same result.
+
+.. warning::
+
+   Deprecation: In version 6, we will remove the optional argument and always return an Expression object. When the
+   result was used as a string nothing will change, but code that checks if the output is a string will no longer
+   function starting from that version.
+
+This will allow consumers to be able to extract types and links to elements from expressions. This allows consumers to,
+for example, interpret the default value for a constructor promoted properties when it directly instantiates an object.
+
+Creating expressions
+--------------------
+
+.. hint::
+
+   The description below is only for internal usage and to understand how expressions work, this library deals with
+   this by default.
+
+In this library, we use the ExpressionPrinter to convert a PHP-Parser node -or expression- into an expression
+like this::
+
+     $printer = new ExpressionPrinter();
+     $expressionTemplate = $printer->prettyPrintExpr($phpParserNode);
+     $expression = new Expression($expressionTemplate, $printer->getParts());
+
+In the example above we assume that there is a PHP-Parser node representing an expression; this node is passed to the
+ExpressionPrinter -which is an adapted PrettyPrinter from PHP-Parser- which will render the expression as a readable
+template string containing placeholders, and a list of parts that can slot into the placeholders.
+
+Consuming expressions
+---------------------
+
+When using this library, you can consume these expression objects either by
+
+1. Directly casting them to a string - this will replace all placeholders with the stringified version of the parts
+2. Use the render function - this will do the same as the previous methods but you can specify one or more overrides
+   for the placeholders in the expression
+
+The second method can be used to create your own string values from the given parts and render, for example, links in
+these locations.
+
+Another way to use these expressions is to interpret the parts array, and through that way know which elements and
+types are referred to in that expression.

docs/index.rst

@@ -25,4 +25,5 @@ are however several advantages to using this library:
 
    getting-started
    reflection-structure
+   expressions
    extending/index

phpstan.neon

@@ -6,7 +6,6 @@ parameters:
     ignoreErrors:
 
         - '#Method phpDocumentor\\Reflection\\File\\LocalFile::md5\(\) should return string but returns string\|false\.#'
-        - '#Else branch is unreachable because ternary operator condition is always true\.#'
         #
         # all these $fqsen errors indicate the need for a decorator class around PhpParser\Node to hold the public $fqsen that Reflection is giving it)
         #

psalm-baseline.xml

@@ -29,6 +29,10 @@
     </MixedArgumentTypeCoercion>
   </file>
   <file src="src/phpDocumentor/Reflection/NodeVisitor/ElementNameResolver.php">
+    <DeprecatedClass>
+      <code><![CDATA[PropertyProperty::class]]></code>
+      <code><![CDATA[PropertyProperty::class]]></code>
+    </DeprecatedClass>
     <ImplicitToStringCast>
       <code><![CDATA[$node->name]]></code>
       <code><![CDATA[$node->name]]></code>
@@ -53,9 +57,6 @@
     <PossiblyUndefinedMethod>
       <code><![CDATA[addConstant]]></code>
     </PossiblyUndefinedMethod>
-    <RedundantCondition>
-      <code><![CDATA[$const->getValue() !== null]]></code>
-    </RedundantCondition>
   </file>
   <file src="src/phpDocumentor/Reflection/Php/Factory/ClassConstantIterator.php">
     <MixedReturnStatement>
@@ -115,11 +116,6 @@
       <code><![CDATA[$object->getAttribute('fqsen')]]></code>
     </MixedArgument>
   </file>
-  <file src="src/phpDocumentor/Reflection/Php/Factory/GlobalConstant.php">
-    <RedundantCondition>
-      <code><![CDATA[$const->getValue() !== null]]></code>
-    </RedundantCondition>
-  </file>
   <file src="src/phpDocumentor/Reflection/Php/Factory/GlobalConstantIterator.php">
     <MixedReturnStatement>
       <code><![CDATA[$this->constant->consts[$this->index]->getAttribute('fqsen')]]></code>

psalm.xml

@@ -9,6 +9,11 @@
     <projectFiles>
         <directory name="src" />
         <ignoreFiles>
+            <!--
+            ExpressionPrinter inherits all kinds of errors from PHP-Parser that I cannot fix, until a solution is found
+            we ignore this
+            -->
+            <file name="src/phpDocumentor/Reflection/Php/Expression/ExpressionPrinter.php"/>
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>

src/phpDocumentor/Reflection/NodeVisitor/ElementNameResolver.php

@@ -17,6 +17,7 @@
 use phpDocumentor\Reflection\Fqsen;
 use PhpParser\Node;
 use PhpParser\Node\Const_;
+use PhpParser\Node\PropertyItem;
 use PhpParser\Node\Stmt\Class_;
 use PhpParser\Node\Stmt\ClassConst;
 use PhpParser\Node\Stmt\ClassMethod;
@@ -72,6 +73,7 @@ public function leaveNode(Node $node)
             case ClassMethod::class:
             case Trait_::class:
             case PropertyProperty::class:
+            case PropertyItem::class:
             case Node\PropertyItem::class:
             case ClassConst::class:
             case Const_::class:

src/phpDocumentor/Reflection/Php/Argument.php

@@ -16,6 +16,11 @@
 use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\Types\Mixed_;
 
+use function is_string;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * Descriptor representing a single Argument of a method or function.
  *
@@ -33,8 +38,8 @@ public function __construct(
         /** @var string name of the Argument */
         private readonly string $name,
         Type|null $type = null,
-        /** @var string|null the default value for an argument or null if none is provided */
-        private readonly string|null $default = null,
+        /** @var Expression|string|null the default value for an argument or null if none is provided */
+        private Expression|string|null $default = null,
         /** @var bool whether the argument passes the parameter by reference instead of by value */
         private readonly bool $byReference = false,
         /** @var bool Determines if this Argument represents a variadic argument */
@@ -44,6 +49,15 @@ public function __construct(
             $type = new Mixed_();
         }
 
+        if (is_string($this->default)) {
+            trigger_error(
+                'Default values for arguments should be of type Expression, support for strings will be '
+                . 'removed in 7.x',
+                E_USER_DEPRECATED,
+            );
+            $this->default = new Expression($this->default, []);
+        }
+
         $this->type = $type;
     }
 
@@ -60,8 +74,21 @@ public function getType(): Type|null
         return $this->type;
     }
 
-    public function getDefault(): string|null
+    public function getDefault(bool $asString = true): Expression|string|null
     {
+        if ($this->default === null) {
+            return null;
+        }
+
+        if ($asString) {
+            trigger_error(
+                'The Default value will become of type Expression by default',
+                E_USER_DEPRECATED,
+            );
+
+            return (string) $this->default;
+        }
+
         return $this->default;
     }
 

src/phpDocumentor/Reflection/Php/Constant.php

@@ -20,6 +20,11 @@
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
+use function is_string;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * Descriptor representing a constant
  *
@@ -42,7 +47,7 @@ final class Constant implements Element, MetaDataContainerInterface, AttributeCo
     public function __construct(
         private readonly Fqsen $fqsen,
         private readonly DocBlock|null $docBlock = null,
-        private readonly string|null $value = null,
+        private Expression|string|null $value = null,
         Location|null $location = null,
         Location|null $endLocation = null,
         Visibility|null $visibility = null,
@@ -51,13 +56,37 @@ public function __construct(
         $this->location = $location ?: new Location(-1);
         $this->endLocation = $endLocation ?: new Location(-1);
         $this->visibility = $visibility ?: new Visibility(Visibility::PUBLIC_);
+
+        if (!is_string($this->value)) {
+            return;
+        }
+
+        trigger_error(
+            'Constant values should be of type Expression, support for strings will be '
+            . 'removed in 6.x',
+            E_USER_DEPRECATED,
+        );
+        $this->value = new Expression($this->value, []);
     }
 
     /**
-     * Returns the value of this constant.
+     * Returns the expression value for this constant.
      */
-    public function getValue(): string|null
+    public function getValue(bool $asString = true): Expression|string|null
     {
+        if ($this->value === null) {
+            return null;
+        }
+
+        if ($asString) {
+            trigger_error(
+                'The expression value will become of type Expression by default',
+                E_USER_DEPRECATED,
+            );
+
+            return (string) $this->value;
+        }
+
         return $this->value;
     }
 

src/phpDocumentor/Reflection/Php/EnumCase.php

@@ -11,6 +11,11 @@
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
+use function is_string;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * Represents a case in an Enum.
  *
@@ -30,7 +35,7 @@ public function __construct(
         private readonly DocBlock|null $docBlock,
         Location|null $location = null,
         Location|null $endLocation = null,
-        private readonly string|null $value = null,
+        private Expression|string|null $value = null,
     ) {
         if ($location === null) {
             $location = new Location(-1);
@@ -42,6 +47,16 @@ public function __construct(
 
         $this->location = $location;
         $this->endLocation = $endLocation;
+        if (!is_string($this->value)) {
+            return;
+        }
+
+        trigger_error(
+            'Expression values for enum cases should be of type Expression, support for strings will be '
+            . 'removed in 7.x',
+            E_USER_DEPRECATED,
+        );
+        $this->value = new Expression($this->value, []);
     }
 
     #[Override]
@@ -71,8 +86,24 @@ public function getEndLocation(): Location
         return $this->endLocation;
     }
 
-    public function getValue(): string|null
+    /**
+     * Returns the value for this enum case.
+     */
+    public function getValue(bool $asString = true): Expression|string|null
     {
+        if ($this->value === null) {
+            return null;
+        }
+
+        if ($asString) {
+            trigger_error(
+                'The enum case value will become of type Expression by default',
+                E_USER_DEPRECATED,
+            );
+
+            return (string) $this->value;
+        }
+
         return $this->value;
     }
 }