Land the ElementLookup and null handling stack on main

benchmarks/scripts/profile_encode.php

@@ -204,12 +204,12 @@
 }
 printf("typeIso->from(\$element) (no parse):   %6.1fus/call\n", (hrtime(true) - $t0) / 1e3 / $N);
 
-// Step 4: Just DocumentToLookupArrayReader
+// Step 4: ElementLookup, what ObjectEncoder decodes from
 $t0 = hrtime(true);
 for ($i = 0; $i < $N; $i++) {
-    (new \Soap\Encoding\Xml\Reader\DocumentToLookupArrayReader())($partElement);
+    \Soap\Encoding\Xml\Node\ElementLookup::fromElement($partElement);
 }
-printf("DocumentToLookupArrayReader:          %6.1fus/call\n", (hrtime(true) - $t0) / 1e3 / $N);
+printf("ElementLookup::fromElement:           %6.1fus/call\n", (hrtime(true) - $t0) / 1e3 / $N);
 
 // Step 5: object_data from (properties_set)
 $objectDataIso = \VeeWee\Reflecta\Iso\object_data(\stdClass::class);

composer.json

@@ -39,7 +39,7 @@
         "php-soap/engine": "^2.21",
         "php-soap/wsdl": "^1.19",
         "php-soap/xml": "^1.10",
-        "php-soap/wsdl-reader": "~0.32"
+        "php-soap/wsdl-reader": "~0.34"
     },
     "require-dev": {
         "vimeo/psalm": "~6.13",

src/Encoder/AnyElementEncoder.php

@@ -4,7 +4,7 @@
 
 use Soap\Encoding\Xml\Node\Element;
 use Soap\Encoding\Xml\Node\ElementList;
-use Soap\Encoding\Xml\Reader\DocumentToLookupArrayReader;
+use Soap\Encoding\Xml\Node\ElementLookup;
 use Soap\Engine\Metadata\Model\Property;
 use Soap\Engine\Metadata\Model\Type;
 use VeeWee\Reflecta\Iso\Iso;
@@ -21,9 +21,7 @@
 /**
  * @implements XmlEncoder<array|string|null, array<array-key, string>|string|null, string, ElementList|string>
  *
- * @psalm-import-type LookupArray from DocumentToLookupArrayReader
- *
- * @template-implements Feature\ProvidesObjectDecoderLens<LookupArray, LookupArray, ElementList, ElementList>
+ * @template-implements Feature\ProvidesObjectDecoderLens<ElementLookup, ElementLookup, ElementList, ElementList>
  */
 final class AnyElementEncoder implements Feature\ListAware, Feature\OptionalAware, Feature\ProvidesObjectDecoderLens, XmlEncoder
 {
@@ -32,32 +30,27 @@ final class AnyElementEncoder implements Feature\ListAware, Feature\OptionalAwar
      * It will contain all the XML tags available in the object that is surrounding the 'any' property.
      * Properties that are already known by the object, will be omitted.
      *
-     * @return Lens<LookupArray, LookupArray, ElementList, ElementList>
+     * @return Lens<ElementLookup, ElementLookup, ElementList, ElementList>
      */
     public static function createObjectDecoderLens(Type $parentType, Property $currentProperty): Lens
     {
-        $omittedKeys = reduce(
+        $omittedKeys = array_flip(reduce(
             $parentType->getProperties(),
             static fn (array $omit, Property $property): array => [
                 ...$omit,
                 ...($property->getName() !== $currentProperty->getName() ? [$property->getName()] : []),
             ],
             []
-        );
+        ));
 
-        /**
-         * @param LookupArray $data
-         * @return LookupArray
-         */
-        $omit = static fn (array $data): array => diff_by_key($data, array_flip($omittedKeys));
-
-        /** @var Lens<LookupArray, LookupArray, ElementList, ElementList> */
+        /** @var Lens<ElementLookup, ElementLookup, ElementList, ElementList> */
         return Lens::readonly(
-            /**
-             * @psalm-suppress MixedArgumentTypeCoercion - Psalm gets confused about the result of omit.
-             * @param LookupArray $data
-             */
-            static fn (array $data): ElementList => ElementList::fromLookupArray($omit($data))
+            static function (ElementLookup $lookup) use ($omittedKeys): ElementList {
+                /** @var array<string, Element|ElementList> $children */
+                $children = diff_by_key($lookup->children(), $omittedKeys);
+
+                return ElementList::fromLookupArray($children);
+            }
         );
     }
 

src/Encoder/ErrorHandlingEncoder.php

@@ -16,7 +16,7 @@
  * @implements XmlEncoder<TDataIn, TDataOut, TXmlOut, TXmlIn>
  * @implements Feature\DecoratingEncoder<TDataIn, TDataOut, TXmlOut, TXmlIn>
  */
-final class ErrorHandlingEncoder implements Feature\DecoratingEncoder, XmlEncoder
+final class ErrorHandlingEncoder implements Feature\DecoratingEncoder, Feature\NullValueAware, XmlEncoder
 {
     /**
      * @param XmlEncoder<TDataIn, TDataOut, TXmlOut, TXmlIn> $encoder
@@ -34,6 +34,13 @@ public function decoratedEncoder(): XmlEncoder
         return $this->encoder;
     }
 
+    public function nullValueHandling(Context $context): NullValueHandling
+    {
+        return $this->encoder instanceof Feature\NullValueAware
+            ? $this->encoder->nullValueHandling($context)
+            : NullValueHandling::Write;
+    }
+
     /**
      * @return Iso<TDataIn, TDataOut, TXmlOut, TXmlIn>
      */

src/Encoder/Feature/NullValueAware.php

@@ -0,0 +1,14 @@
+<?php declare(strict_types=1);
+
+namespace Soap\Encoding\Encoder\Feature;
+
+use Soap\Encoding\Encoder\Context;
+use Soap\Encoding\Encoder\NullValueHandling;
+
+/**
+ * Tells an object encoder what to do with a null value in this context, so it can leave the element out without calling the encoder.
+ */
+interface NullValueAware
+{
+    public function nullValueHandling(Context $context): NullValueHandling;
+}

src/Encoder/Feature/ProvidesObjectDecoderLens.php

@@ -2,15 +2,17 @@
 
 namespace Soap\Encoding\Encoder\Feature;
 
+use Soap\Encoding\Xml\Node\ElementLookup;
 use Soap\Engine\Metadata\Model\Property;
 use Soap\Engine\Metadata\Model\Type;
 use VeeWee\Reflecta\Lens\LensInterface;
 
 /**
  * When an encoder implements this feature interface, it knows how to create a lens that will be applied on the parent data that is being decoded.
+ * The lens reads from the ElementLookup of the parent element, for example $lookup->element('name') or $lookup->attribute('name').
  *
- * @template-covariant S of array<array-key, mixed>
- * @template-covariant T of array<array-key, mixed>
+ * @template-covariant S of ElementLookup
+ * @template-covariant T of ElementLookup
  * @template-covariant A
  * @template-covariant B
  */

src/Encoder/NullValueHandling.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types=1);
+
+namespace Soap\Encoding\Encoder;
+
+/**
+ * What ObjectEncoder does with a property that is null or absent from the PHP value.
+ * An absent property reads as null, unless the case below tells them apart.
+ */
+enum NullValueHandling
+{
+    /**
+     * Pass null to the property's encoder and write what it returns.
+     * For a nillable element that is the element with xsi:nil="true".
+     */
+    case Write;
+
+    /**
+     * Write nothing for the property, so the element is left out.
+     */
+    case Skip;
+
+    /**
+     * Write nothing when the property is absent from the PHP value.
+     * When it is set to null, behave like Write.
+     */
+    case SkipWhenAbsent;
+}