Expand docs and fix linting and analysis issues

Author: mvriel

docs/expressions.rst

@@ -24,3 +24,37 @@ $isString as being false, it will return an Expression object; which, when cast
 
 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.

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/Php/Constant.php

@@ -43,6 +43,8 @@ final class Constant implements Element, MetaDataContainerInterface, AttributeCo
 
     /**
      * Initializes the object.
+     *
+     * @param Expression|string|null $value
      */
     public function __construct(
         private readonly Fqsen $fqsen,

src/phpDocumentor/Reflection/Php/Expression.php

@@ -5,48 +5,143 @@
 namespace phpDocumentor\Reflection\Php;
 
 use phpDocumentor\Reflection\Fqsen;
+use phpDocumentor\Reflection\Php\Expression\ExpressionPrinter;
 use phpDocumentor\Reflection\Type;
+use Webmozart\Assert\Assert;
 
 use function array_keys;
-use function array_map;
+use function md5;
 use function str_replace;
 
+/**
+ * Represents an expression with a define statement, constant, property, enum case and any other location.
+ *
+ * Certain expressions contain useful references to other elements or types. Examples of these are:
+ *
+ * - Define statements that use an expression to refer to a class or function
+ * - Properties whose default value refers to a constant
+ * - Arguments whose default value initialize an object
+ * - Enum Cases that refer to a function or constant
+ *
+ * This class represents every location where an expression is used and contains 2 pieces of information:
+ *
+ * - The expression string containing placeholders linking to useful information
+ * - An array of 'parts' whose keys equal the placeholders in the expression string and whose values is the extracted
+ *   information, such as an {@see FQSEN} or {@see Type}.
+ *
+ * In a way, the expression string is similar in nature to a URI Template (see links) where you have a string containing
+ * variables that can be replaced. These variables are delimited by `{{` and `}}`, and are build up of the prefix PHPDOC
+ * and then an MD5 hash of the name of the extracted information.
+ *
+ * It is not necessary for a consumer to interpret the information when they do not need it, a {@see self::__toString()}
+ * magic method is provided that will replace the placeholders with the `toString()` output of each part.
+ *
+ * @link https://github.com/php/php-langspec/blob/master/spec/10-expressions.md
+ *     for the definition of expressions in PHP.
+ * @link https://www.rfc-editor.org/rfc/rfc6570 for more information on URI Templates.
+ * @see ExpressionPrinter how an expression coming from PHP-Parser is transformed into an expression.
+ */
 final class Expression
 {
+    /** @var string The expression string containing placeholders for any extracted Types or FQSENs. */
     private string $expression;
 
-    /** @var array<string, Fqsen|Type> */
+    /**
+     * The collection of placeholders with the value that their holding.
+     *
+     * In the expression string there can be several placeholders, this array contains a placeholder => value pair
+     * that can be used by consumers to map the data to another formatting, adding links for example, and then render
+     * the expression.
+     *
+     * @var array<string, Fqsen|Type>
+     */
     private array $parts;
 
+    /**
+     * Returns the recommended placeholder string format given a name.
+     *
+     * Consumers can use their own formats when needed, the placeholders are all keys in the {@see self::$parts} array
+     * and not interpreted by this class. However, to prevent collisions it is recommended to use this method to
+     * generate a placeholder.
+     *
+     * @param string $name a string identifying the element for which the placeholder is generated.
+     */
+    public static function generatePlaceholder(string $name): string
+    {
+        Assert::notEmpty($name);
+
+        return '{{ PHPDOC' . md5($name) . ' }}';
+    }
+
     /**
      * @param array<string, Fqsen|Type> $parts
      */
     public function __construct(string $expression, array $parts)
     {
+        Assert::notEmpty($expression);
+        Assert::allIsInstanceOfAny($parts, [Fqsen::class, Type::class]);
+
         $this->expression = $expression;
         $this->parts = $parts;
     }
 
+    /**
+     * The raw expression string containing placeholders for any extracted Types or FQSENs.
+     *
+     * @see self::render() to render a human-readable expression and to replace some parts with custom values.
+     * @see self::__toString() to render a human-readable expression with the previously extracted parts.
+     */
     public function getExpression(): string
     {
         return $this->expression;
     }
 
     /**
+     * A list of extracted parts for which placeholders exist in the expression string.
+     *
+     * The returned array will have the placeholders of the expression string as keys, and the related FQSEN or Type as
+     * value. This can be used as a basis for doing your own transformations to {@see self::render()} the expression
+     * in a custom way; or to extract type information from an expression and use that elsewhere in your application.
+     *
+     * @see ExpressionPrinter to transform a PHP-Parser expression into an expression string and list of parts.
+     *
      * @return array<string, Fqsen|Type>
      */
     public function getParts(): array
     {
         return $this->parts;
     }
 
-    public function __toString(): string
+    /**
+     * Renders the expression as a string and replaces all placeholders with either a provided value, or the
+     * stringified value from the parts in this expression.
+     *
+     * The keys of the replacement parts should match those of {@see self::getParts()}, any unrecognized key is not
+     * handled.
+     *
+     * @param array<string, string> $replacementParts
+     */
+    public function render(array $replacementParts = []): string
     {
-        $valuesAsStrings = array_map(
-            static fn (object $part): string => (string) $part,
-            $this->parts
-        );
+        Assert::allStringNotEmpty($replacementParts);
+
+        $valuesAsStrings = [];
+        foreach ($this->parts as $placeholder => $part) {
+            $valuesAsStrings[$placeholder] = $replacementParts[$placeholder] ?? (string) $part;
+        }
 
         return str_replace(array_keys($this->parts), $valuesAsStrings, $this->expression);
     }
+
+    /**
+     * Returns a rendered version of the expression string where all placeholders are replaced by the stringified
+     * versions of the included parts.
+     *
+     * @see self::$parts for the list of parts used in rendering
+     * @see self::render() to influence rendering of the expression.
+     */
+    public function __toString(): string
+    {
+        return $this->render();
+    }
 }

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

@@ -5,14 +5,14 @@
 namespace phpDocumentor\Reflection\Php\Expression;
 
 use phpDocumentor\Reflection\Fqsen;
+use phpDocumentor\Reflection\Php\Expression;
+use phpDocumentor\Reflection\Type;
 use PhpParser\Node\Name;
 use PhpParser\PrettyPrinter\Standard;
 
-use function md5;
-
 final class ExpressionPrinter extends Standard
 {
-    /** @var array<Fqsen> */
+    /** @var array<string, Fqsen|Type> */
     private array $parts = [];
 
     protected function resetState(): void
@@ -25,16 +25,24 @@ protected function resetState(): void
     protected function pName(Name $node): string
     {
         $renderedName = parent::pName($node);
-        $code = md5($renderedName);
+        $placeholder = Expression::generatePlaceholder($renderedName);
+        $this->parts[$placeholder] = new Fqsen('\\' . $renderedName);
 
-        $placeholder = '{{ PHPDOC' . $code . ' }}';
-        $this->parts[$placeholder] = new Fqsen('\\' . $node);
+        return $placeholder;
+    }
+
+    // phpcs:ignore PSR1.Methods.CamelCapsMethodName.NotCamelCaps
+    protected function pName_FullyQualified(Name\FullyQualified $node): string
+    {
+        $renderedName = parent::pName_FullyQualified($node);
+        $placeholder = Expression::generatePlaceholder($renderedName);
+        $this->parts[$placeholder] = new Fqsen($renderedName);
 
         return $placeholder;
     }
 
     /**
-     * @return array<Fqsen>
+     * @return array<string, Fqsen|Type>
      */
     public function getParts(): array
     {

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

@@ -109,13 +109,9 @@ protected function doCreate(
         return null;
     }
 
-    private function determineValue(ClassConstantIterator $value): null|Expression
+    private function determineValue(ClassConstantIterator $value): Expression|null
     {
-        $expression = $value->getValue() !== null ? $this->valueConverter->prettyPrintExpr($value->getValue()) : null;
-        if ($expression === null) {
-            return null;
-        }
-
+        $expression = $this->valueConverter->prettyPrintExpr($value->getValue());
         if ($this->valueConverter instanceof ExpressionPrinter) {
             $expression = new Expression($expression, $this->valueConverter->getParts());
         }

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

@@ -127,11 +127,7 @@ private function determineValue(Arg|null $value): ValueExpression|null
             return null;
         }
 
-        $expression = $value->value !== null ? $this->valueConverter->prettyPrintExpr($value->value) : null;
-        if ($expression === null) {
-            return null;
-        }
-
+        $expression = $this->valueConverter->prettyPrintExpr($value->value);
         if ($this->valueConverter instanceof ExpressionPrinter) {
             $expression = new ValueExpression($expression, $this->valueConverter->getParts());
         }

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

@@ -10,7 +10,6 @@
 use phpDocumentor\Reflection\Php\Enum_ as EnumElement;
 use phpDocumentor\Reflection\Php\EnumCase as EnumCaseElement;
 use phpDocumentor\Reflection\Php\Factory\Reducer\Reducer;
-use phpDocumentor\Reflection\Php\Expression;
 use phpDocumentor\Reflection\Php\Expression as ValueExpression;
 use phpDocumentor\Reflection\Php\Expression\ExpressionPrinter;
 use phpDocumentor\Reflection\Php\StrategyContainer;

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

@@ -84,13 +84,9 @@ protected function doCreate(
         return null;
     }
 
-    private function determineValue(GlobalConstantIterator $value): ?Expression
+    private function determineValue(GlobalConstantIterator $value): Expression
     {
-        $expression = $value->getValue() !== null ? $this->valueConverter->prettyPrintExpr($value->getValue()) : null;
-        if ($expression === null) {
-            return null;
-        }
-
+        $expression = $this->valueConverter->prettyPrintExpr($value->getValue());
         if ($this->valueConverter instanceof ExpressionPrinter) {
             $expression = new Expression($expression, $this->valueConverter->getParts());
         }

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

@@ -111,10 +111,8 @@ protected function doCreate(
 
     private function determineDefault(PropertyIterator $value): Expression|null
     {
-        $expression = $value->getDefault() !== null
-            ? $this->valueConverter->prettyPrintExpr($value->getDefault())
-            : null;
-
+        $default = $value->getDefault();
+        $expression = $default !== null ? $this->valueConverter->prettyPrintExpr($default) : null;
         if ($expression === null) {
             return null;
         }