Improve mapping logic

Author: Kirill Nesmeyanov

src/Mapping/Driver/AttributeDriver.php

@@ -12,6 +12,7 @@
 use TypeLang\Mapper\Mapping\MapName;
 use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Mapper\Mapping\Metadata\ClassMetadata;
+use TypeLang\Mapper\Mapping\Metadata\ExpressionMetadata;
 use TypeLang\Mapper\Mapping\Metadata\TypeMetadata;
 use TypeLang\Mapper\Mapping\NormalizeAsArray;
 use TypeLang\Mapper\Mapping\SkipWhen;
@@ -90,9 +91,12 @@ protected function load(
             $attribute = $this->findPropertyAttribute($property, MapType::class);
 
             if ($attribute !== null) {
-                $type = $this->createType($attribute->type, $property, $types, $parser);
-
-                $metadata->setTypeInfo($type);
+                $metadata->setTypeInfo($this->createType(
+                    type: $attribute->type,
+                    property: $property,
+                    types: $types,
+                    parser: $parser,
+                ));
             }
 
             // -----------------------------------------------------------------
@@ -112,11 +116,12 @@ protected function load(
             $attribute = $this->findPropertyAttribute($property, SkipWhen::class);
 
             if ($attribute !== null) {
-                $expression = $this->createExpression($attribute->expr, [
-                    'this',
-                ]);
-
-                $metadata->setSkipCondition($expression);
+                $metadata->setSkipCondition(new ExpressionMetadata(
+                    expression: $this->createExpression($attribute->expr, [
+                        $attribute->context,
+                    ]),
+                    context: $attribute->context,
+                ));
             }
         }
     }

src/Mapping/Metadata/ClassMetadata.php

@@ -10,15 +10,26 @@
 use TypeLang\Parser\Node\Stmt\TypeStatement;
 
 /**
+ * Represents an abstraction over general information about a class.
+ *
  * @template T of object
  */
 final class ClassMetadata extends Metadata
 {
     /**
+     * Contains a list of class fields available for
+     * normalization and denormalization.
+     *
      * @var array<non-empty-string, PropertyMetadata>
      */
     private array $properties = [];
 
+    /**
+     * Contains a {@see bool} flag that is responsible for converting the
+     * object into an associative {@see array} during normalization.
+     *
+     * If {@see null}, then the system setting should be used.
+     */
     private ?bool $normalizeAsArray = null;
 
     /**
@@ -40,6 +51,8 @@ public function __construct(
     /**
      * Dynamically creates AST class representation.
      *
+     * Required to print type information in exceptions.
+     *
      * @api
      *
      * @codeCoverageIgnore
@@ -70,7 +83,7 @@ public function getTypeStatement(Context $context): TypeStatement
     }
 
     /**
-     * Returns class name.
+     * Returns full qualified class name.
      *
      * @return class-string<T>
      */
@@ -80,6 +93,17 @@ public function getName(): string
     }
 
     /**
+     * Returns information about the normalization method of an object.
+     *
+     * - Returns {@see true} if the object should be normalized as
+     *   an associative {@see array}.
+     *
+     * - Returns {@see false} if the object should be normalized as an
+     *   anonymous {@see object}.
+     *
+     * - Returns {@see null} if the system settings for this option
+     *   should be used.
+     *
      * @api
      */
     public function isNormalizeAsArray(): ?bool
@@ -88,6 +112,8 @@ public function isNormalizeAsArray(): ?bool
     }
 
     /**
+     * Forces the object normalization option.
+     *
      * @api
      */
     public function shouldNormalizeAsArray(?bool $enabled = null): void
@@ -96,6 +122,9 @@ public function shouldNormalizeAsArray(?bool $enabled = null): void
     }
 
     /**
+     * Adds {@see PropertyMetadata} property information to
+     * the {@see ClassMetadata} instance.
+     *
      * @api
      */
     public function addProperty(PropertyMetadata $property): void
@@ -104,6 +133,10 @@ public function addProperty(PropertyMetadata $property): void
     }
 
     /**
+     * Returns {@see PropertyMetadata} information about the property.
+     *
+     * If it was previously absent, it creates a new one.
+     *
      * @api
      *
      * @param non-empty-string $name
@@ -114,6 +147,10 @@ public function getPropertyOrCreate(string $name): PropertyMetadata
     }
 
     /**
+     * Returns {@see PropertyMetadata} information about a property,
+     * or returns {@see null} if no such property has been registered
+     * in the {@see ClassMetadata} instance.
+     *
      * @api
      *
      * @param non-empty-string $name
@@ -124,6 +161,10 @@ public function findProperty(string $name): ?PropertyMetadata
     }
 
     /**
+     * Returns {@see true} if the {@see PropertyMetadata} property information
+     * was registered in the {@see ClassMetadata} instance
+     * and {@see false} otherwise.
+     *
      * @api
      *
      * @param non-empty-string $name
@@ -134,6 +175,8 @@ public function hasProperty(string $name): bool
     }
 
     /**
+     * Returns a list of registered {@see PropertyMetadata} properties.
+     *
      * @return list<PropertyMetadata>
      */
     public function getProperties(): array

src/Mapping/Metadata/ExpressionMetadata.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Mapping\Metadata;
+
+use Symfony\Component\ExpressionLanguage\ParsedExpression;
+
+final class ExpressionMetadata extends Metadata
+{
+    /**
+     * @var non-empty-string
+     */
+    public const DEFAULT_CONTEXT_VARIABLE_NAME = 'this';
+
+    /**
+     * @param non-empty-string $context
+     */
+    public function __construct(
+        private readonly ParsedExpression $expression,
+        private readonly string $context = self::DEFAULT_CONTEXT_VARIABLE_NAME,
+        ?int $createdAt = null,
+    ) {
+        parent::__construct($createdAt);
+    }
+
+    /**
+     * @api
+     *
+     * @return non-empty-string
+     */
+    public function getContextVariableName(): string
+    {
+        return $this->context;
+    }
+
+    /**
+     * @api
+     */
+    public function getExpression(): ParsedExpression
+    {
+        return $this->expression;
+    }
+}

src/Mapping/Metadata/PropertyMetadata.php

@@ -4,7 +4,6 @@
 
 namespace TypeLang\Mapper\Mapping\Metadata;
 
-use Symfony\Component\ExpressionLanguage\ParsedExpression;
 use TypeLang\Mapper\Runtime\Context;
 use TypeLang\Parser\Node\Stmt\NamedTypeNode;
 use TypeLang\Parser\Node\Stmt\Shape\NamedFieldNode;
@@ -21,7 +20,7 @@ final class PropertyMetadata extends Metadata
 
     private bool $hasDefaultValue = false;
 
-    private ?ParsedExpression $skipWhen = null;
+    private ?ExpressionMetadata $skipWhen = null;
 
     /**
      * @param non-empty-string $export
@@ -158,7 +157,7 @@ public function findTypeInfo(): ?TypeMetadata
     /**
      * @api
      */
-    public function setSkipCondition(ParsedExpression $expression): void
+    public function setSkipCondition(ExpressionMetadata $expression): void
     {
         $this->skipWhen = $expression;
     }
@@ -180,14 +179,15 @@ public function hasSkipCondition(): bool
     }
 
     /**
-     * Note: The prefix "find" is used to indicate that the {@see ParsedExpression}
-     *       definition may be optional and method may return {@see null}.
-     *       The prefix "get" is used when the value is forced to be obtained
-     *       and should throw an exception if the type definition is missing.
+     * Note: The prefix "find" is used to indicate that the
+     *       {@see ExpressionMetadata} definition may be optional and method
+     *       may return {@see null}. The prefix "get" is used when the value
+     *       is forced to be obtained and should throw an exception if the type
+     *       definition is missing.
      *
      * @api
      */
-    public function findSkipCondition(): ?ParsedExpression
+    public function findSkipCondition(): ?ExpressionMetadata
     {
         return $this->skipWhen;
     }

src/Mapping/SkipWhen.php

@@ -5,15 +5,30 @@
 namespace TypeLang\Mapper\Mapping;
 
 use JetBrains\PhpStorm\Language;
+use TypeLang\Mapper\Mapping\Metadata\ExpressionMetadata;
 
 #[\Attribute(\Attribute::TARGET_PROPERTY)]
 class SkipWhen
 {
     public function __construct(
         /**
+         * Contains an expression for which the field will be skipped
+         * during normalization.
+         *
+         * Requires "`symfony/expression-language`" package to be installed.
+         *
+         * @link https://symfony.com/doc/current/components/expression_language.html
+         *
          * @var non-empty-string
          */
         #[Language('JavaScript')]
         public readonly string $expr,
+        /**
+         * Contains the name of the variable that will hold the reference
+         * of the object.
+         *
+         * @var non-empty-string
+         */
+        public readonly string $context = ExpressionMetadata::DEFAULT_CONTEXT_VARIABLE_NAME,
     ) {}
 }

src/Type/ObjectType/ObjectTypeNormalizer.php

@@ -98,9 +98,12 @@ protected function normalizeObject(object $object, Context $context): array
             $skip = $meta->findSkipCondition();
 
             if ($skip !== null) {
-                $nodes = $skip->getNodes();
+                $expression = $skip->getExpression();
+                $variable = $skip->getContextVariableName();
 
-                if ((bool) $nodes->evaluate([], ['this' => $object])) {
+                $nodes = $expression->getNodes();
+
+                if ((bool) $nodes->evaluate([], [$variable => $object])) {
                     continue;
                 }
             }