Started reworking expression strings into Expression objects

Values of constants, named arguments, etc, should be parsed to include
types and FQSENs that can be used in phpDocumentor to display links
with. Since these are now simple strings, I have refactored this into a
template string system with placeholder values that a consumer could
replace with its own values.

Author: mvriel

Makefile

@@ -16,16 +16,16 @@ static-code-analysis: vendor ## Runs a static code analysis with phpstan/phpstan
 	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/psalm
 
 .PHONY: test
-test: test-unit test-functional ## Runs all test suites with phpunit/phpunit
+test: test-unit test-integration ## Runs all test suites with phpunit/phpunit
 	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/phpunit
 
 .PHONY: test-unit
 test-unit: ## Runs unit tests with phpunit/phpunit
 	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/phpunit --testsuite=unit
 
-.PHONY: test-functional
-test-functional: ## Runs unit tests with phpunit/phpunit
-	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/phpunit --testsuite=functional
+.PHONY: test-integration
+test-integration: ## Runs unit tests with phpunit/phpunit
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.4 vendor/bin/phpunit --testsuite=integration
 
 .PHONY: dependency-analysis
 dependency-analysis: vendor ## Runs a dependency analysis with maglnet/composer-require-checker

src/phpDocumentor/Reflection/Php/Argument.php

@@ -27,8 +27,8 @@ final class Argument
     /** @var Type a normalized type that should be in this Argument */
     private Type $type;
 
-    /** @var string|null the default value for an argument or null if none is provided */
-    private ?string $default;
+    /** @var Expression|null the default value for an argument or null if none is provided */
+    private ?Expression $default;
 
     /** @var bool whether the argument passes the parameter by reference instead of by value */
     private bool $byReference;
@@ -38,22 +38,33 @@ final class Argument
 
     /**
      * Initializes the object.
+     *
+     * @param string|Expression|null $default
      */
     public function __construct(
         string $name,
         ?Type $type = null,
-        ?string $default = null,
+        $default = null,
         bool $byReference = false,
         bool $isVariadic = false
     ) {
         $this->name = $name;
-        $this->default = $default;
         $this->byReference = $byReference;
         $this->isVariadic = $isVariadic;
         if ($type === null) {
             $type = new Mixed_();
         }
 
+        if (is_string($default)) {
+            trigger_error(
+                'Default values for arguments should be of type Expression, support for strings will be '
+                . 'removed in 6.x',
+                E_USER_DEPRECATED
+            );
+            $default = new Expression($default, []);
+        }
+        $this->default = $default;
+
         $this->type = $type;
     }
 
@@ -70,8 +81,20 @@ public function getType(): ?Type
         return $this->type;
     }
 
-    public function getDefault(): ?string
+    /**
+     * @return Expression|string|null
+     */
+    public function getDefault(bool $asString = true)
     {
+        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

@@ -30,7 +30,10 @@ final class Constant implements Element, MetaDataContainerInterface
 
     private ?DocBlock $docBlock;
 
-    private ?string $value;
+    /**
+     * @var string|Expression|null
+     */
+    private $value;
 
     private Location $location;
 
@@ -46,26 +49,47 @@ final class Constant implements Element, MetaDataContainerInterface
     public function __construct(
         Fqsen $fqsen,
         ?DocBlock $docBlock = null,
-        ?string $value = null,
+        $value = null,
         ?Location $location = null,
         ?Location $endLocation = null,
         ?Visibility $visibility = null,
         bool $final = false
     ) {
         $this->fqsen = $fqsen;
         $this->docBlock = $docBlock;
-        $this->value = $value;
         $this->location = $location ?: new Location(-1);
         $this->endLocation = $endLocation ?: new Location(-1);
         $this->visibility = $visibility ?: new Visibility(Visibility::PUBLIC_);
         $this->final = $final;
+
+        if (is_string($value)) {
+            trigger_error(
+                'Constant values should be of type Expression, support for strings will be '
+                . 'removed in 6.x',
+                E_USER_DEPRECATED
+            );
+            $value = new Expression($value, []);
+        }
+        $this->value = $value;
+
     }
 
     /**
-     * Returns the value of this constant.
+     * Returns the expression value for this constant.
+     *
+     * @return Expression|string|null
      */
-    public function getValue(): ?string
+    public function getValue(bool $asString = true)
     {
+        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

@@ -22,14 +22,18 @@ final class EnumCase implements Element, MetaDataContainerInterface
 
     private Location $endLocation;
 
-    private ?string $value;
+    /** @var Expression|string|null */
+    private $value;
 
+    /**
+     * @param Expression|string|null $value
+     */
     public function __construct(
         Fqsen $fqsen,
         ?DocBlock $docBlock,
         ?Location $location = null,
         ?Location $endLocation = null,
-        ?string $value = null
+        $value = null
     ) {
         if ($location === null) {
             $location = new Location(-1);
@@ -43,6 +47,14 @@ public function __construct(
         $this->docBlock = $docBlock;
         $this->location = $location;
         $this->endLocation = $endLocation;
+        if (is_string($value)) {
+            trigger_error(
+                'Expression values for enum cases should be of type Expression, support for strings will be '
+                . 'removed in 6.x',
+                E_USER_DEPRECATED
+            );
+            $value = new Expression($value, []);
+        }
         $this->value = $value;
     }
 
@@ -71,8 +83,22 @@ public function getEndLocation(): Location
         return $this->endLocation;
     }
 
-    public function getValue(): ?string
+    /**
+     * Returns the value for this enum case.
+     *
+     * @return Expression|string|null
+     */
+    public function getValue(bool $asString = true)
     {
+        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;
     }
 }

src/phpDocumentor/Reflection/Php/Expression.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\Php;
+
+use phpDocumentor\Reflection\Fqsen;
+use phpDocumentor\Reflection\Type;
+
+final class Expression
+{
+    private string $expression;
+
+    /** @var array<string, Fqsen|Type> */
+    private array $parts;
+
+    public function __construct(string $expression, array $parts)
+    {
+        $this->expression = $expression;
+        $this->parts = $parts;
+    }
+
+    public function getExpression(): string
+    {
+        return $this->expression;
+    }
+
+    public function getParts(): array
+    {
+        return $this->parts;
+    }
+
+    public function __toString(): string
+    {
+        $valuesAsStrings = array_map(
+            static fn(object $part): string => (string)$part,
+            $this->parts
+        );
+
+        return str_replace(array_keys($this->parts), $valuesAsStrings, $this->expression);
+    }
+}

src/phpDocumentor/Reflection/Php/Expression/ExpressionPrinter.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\Php\Expression;
+
+use phpDocumentor\Reflection\Fqsen;
+use PhpParser\Node\Name;
+use PhpParser\PrettyPrinter\Standard;
+
+final class ExpressionPrinter extends Standard
+{
+    /**
+     * @var array<Fqsen>
+     */
+    private array $parts = [];
+
+    protected function resetState(): void
+    {
+        parent::resetState();
+
+        $this->parts = [];
+    }
+
+    protected function pName(Name $node): string
+    {
+        $renderedName = parent::pName($node);
+        $code = md5($renderedName);
+
+        $placeholder = '{{ PHPDOC' . $code . ' }}';
+        $this->parts[$placeholder] = new Fqsen('\\' . $node);
+
+        return $placeholder;
+    }
+
+    /**
+     * @return array<Fqsen>
+     */
+    public function getParts(): array
+    {
+        return $this->parts;
+    }
+}

src/phpDocumentor/Reflection/Php/Factory/Argument.php

@@ -14,6 +14,8 @@
 namespace phpDocumentor\Reflection\Php\Factory;
 
 use phpDocumentor\Reflection\Php\Argument as ArgumentDescriptor;
+use phpDocumentor\Reflection\Php\Expression;
+use phpDocumentor\Reflection\Php\Expression\ExpressionPrinter;
 use phpDocumentor\Reflection\Php\Function_;
 use phpDocumentor\Reflection\Php\Method;
 use phpDocumentor\Reflection\Php\ProjectFactoryStrategy;
@@ -73,11 +75,16 @@ protected function doCreate(
             ]
         );
 
+        $default = $object->default !== null ? $this->valueConverter->prettyPrintExpr($object->default) : null;
+        if ($this->valueConverter instanceof ExpressionPrinter) {
+            $default = new Expression($default, $this->valueConverter->getParts());
+        }
+
         $method->addArgument(
             new ArgumentDescriptor(
                 (string) $object->var->name,
                 (new Type())->fromPhpParser($object->type),
-                $object->default !== null ? $this->valueConverter->prettyPrintExpr($object->default) : null,
+                $default,
                 $object->byRef,
                 $object->variadic
             )

src/phpDocumentor/Reflection/Php/Factory/ClassConstant.php

@@ -18,6 +18,8 @@
 use phpDocumentor\Reflection\Php\Class_;
 use phpDocumentor\Reflection\Php\Constant as ConstantElement;
 use phpDocumentor\Reflection\Php\Enum_;
+use phpDocumentor\Reflection\Php\Expression;
+use phpDocumentor\Reflection\Php\Expression\ExpressionPrinter;
 use phpDocumentor\Reflection\Php\Interface_;
 use phpDocumentor\Reflection\Php\StrategyContainer;
 use phpDocumentor\Reflection\Php\Trait_;
@@ -79,7 +81,7 @@ protected function doCreate(
             $constantContainer->addConstant(new ConstantElement(
                 $const->getFqsen(),
                 $this->createDocBlock($const->getDocComment(), $context->getTypeContext()),
-                $const->getValue() !== null ? $this->valueConverter->prettyPrintExpr($const->getValue()) : null,
+                $this->determineValue($const),
                 new Location($const->getLine()),
                 new Location($const->getEndLine()),
                 $this->buildVisibility($const),
@@ -88,6 +90,19 @@ protected function doCreate(
         }
     }
 
+    private function determineValue(ClassConstantIterator $value): ?Expression
+    {
+        $expression = $value->getValue() !== null ? $this->valueConverter->prettyPrintExpr($value->getValue()) : null;
+        if ($this->valueConverter instanceof ExpressionPrinter) {
+            $expression = new Expression($expression, $this->valueConverter->getParts());
+        }
+        if (is_string($expression)) {
+            $expression = new Expression($expression, []);
+        }
+
+        return $expression;
+    }
+
     /**
      * Converts the visibility of the constant to a valid Visibility object.
      */

src/phpDocumentor/Reflection/Php/Factory/Define.php

@@ -17,6 +17,8 @@
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Php\Constant as ConstantElement;
+use phpDocumentor\Reflection\Php\Expression as ValueExpression;
+use phpDocumentor\Reflection\Php\Expression\ExpressionPrinter;
 use phpDocumentor\Reflection\Php\File as FileElement;
 use phpDocumentor\Reflection\Php\StrategyContainer;
 use phpDocumentor\Reflection\Php\ValueEvaluator\ConstantEvaluator;
@@ -119,13 +121,21 @@ protected function doCreate(
         $file->addConstant($constant);
     }
 
-    private function determineValue(?Arg $value): ?string
+    private function determineValue(?Arg $value): ?ValueExpression
     {
         if ($value === null) {
             return null;
         }
 
-        return $this->valueConverter->prettyPrintExpr($value->value);
+        $expression = $value->value !== null ? $this->valueConverter->prettyPrintExpr($value->value) : null;
+        if ($this->valueConverter instanceof ExpressionPrinter) {
+            $expression = new ValueExpression($expression, $this->valueConverter->getParts());
+        }
+        if (is_string($expression)) {
+            $expression = new ValueExpression($expression, []);
+        }
+
+        return $expression;
     }
 
     private function determineFqsen(Arg $name, ContextStack $context): ?Fqsen