veewee · Oct 16, 2026 · Oct 15, 2026 · Oct 15, 2026 · Oct 15, 2026 · Oct 15, 2026
diff --git a/benchmarks/ComplexTypeBenchTrait.php b/benchmarks/ComplexTypeBenchTrait.php
@@ -113,7 +113,10 @@ public function setUp(): void
         $this->extSoapEncoded->__soapCall('test', ['testParam' => $this->singleItem]);
     }
 
-    private function buildPhpSoapDriver(string $use): Driver
+    /**
+     * @param string $occurs extra attributes for every element of addressType and itemType, for example minOccurs="0"
+     */
+    private function buildPhpSoapDriver(string $use, string $occurs = ''): Driver
     {
         $encodingStyle = $use === 'encoded'
             ? ' encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"'
@@ -134,22 +137,22 @@ private function buildPhpSoapDriver(string $use): Driver
            <xsd:import namespace="http://schemas.xmlsoap.org/wsdl/" />
             <complexType name="addressType">
                 <sequence>
-                    <element name="street" type="xsd:string"/>
-                    <element name="city" type="xsd:string"/>
-                    <element name="zip" type="xsd:string"/>
+                    <element name="street" type="xsd:string"{$occurs}/>
+                    <element name="city" type="xsd:string"{$occurs}/>
+                    <element name="zip" type="xsd:string"{$occurs}/>
                 </sequence>
             </complexType>
             <complexType name="itemType">
                 <sequence>
-                    <element name="id" type="xsd:int"/>
-                    <element name="name" type="xsd:string"/>
-                    <element name="description" type="xsd:string"/>
-                    <element name="price" type="xsd:float"/>
-                    <element name="quantity" type="xsd:int"/>
-                    <element name="active" type="xsd:boolean"/>
-                    <element name="sku" type="xsd:string"/>
-                    <element name="category" type="xsd:string"/>
-                    <element name="address" type="tns:addressType"/>
+                    <element name="id" type="xsd:int"{$occurs}/>
+                    <element name="name" type="xsd:string"{$occurs}/>
+                    <element name="description" type="xsd:string"{$occurs}/>
+                    <element name="price" type="xsd:float"{$occurs}/>
+                    <element name="quantity" type="xsd:int"{$occurs}/>
+                    <element name="active" type="xsd:boolean"{$occurs}/>
+                    <element name="sku" type="xsd:string"{$occurs}/>
+                    <element name="category" type="xsd:string"{$occurs}/>
+                    <element name="address" type="tns:addressType"{$occurs}/>
                 </sequence>
             </complexType>
           </schema>

diff --git a/benchmarks/EncodeSparseBench.php b/benchmarks/EncodeSparseBench.php
@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Soap\Encoding\Benchmarks;
+
+use PhpBench\Attributes\BeforeMethods;
+use PhpBench\Attributes\Groups;
+use PhpBench\Attributes\Iterations;
+use PhpBench\Attributes\Revs;
+use PhpBench\Attributes\Warmup;
+use Soap\Encoding\Driver;
+
+/**
+ * Encode benchmarks on the itemType of EncodeBench with every element minOccurs="0" nillable="true".
+ *
+ * Read down to compare, per scale:
+ *   - all present: no value is null
+ *   - all null: every element is an explicit null and written as xsi:nil
+ *   - sparse: only id and address.city are set, the other properties are absent and left out
+ */
+#[BeforeMethods('setUp')]
+#[Warmup(2)]
+#[Iterations(5)]
+class EncodeSparseBench
+{
+    use ComplexTypeBenchTrait;
+
+    private Driver $optionalDriver;
+    /** @var list<object> */
+    private array $allPresent;
+    /** @var list<object> */
+    private array $allNull;
+    /** @var list<object> */
+    private array $sparse;
+
+    public function setUp(): void
+    {
+        $this->optionalDriver = $this->buildPhpSoapDriver('literal', ' minOccurs="0" nillable="true"');
+
+        $this->allPresent = [];
+        $this->allNull = [];
+        $this->sparse = [];
+        for ($i = 0; $i < 500; $i++) {
+            $this->allPresent[] = (object) [
+                'id' => $i,
+                'name' => 'Widget ' . $i,
+                'description' => 'Description for widget ' . $i,
+                'price' => 9.99 + $i,
+                'quantity' => $i * 10,
+                'active' => $i % 2 === 0,
+                'sku' => 'WDG-' . str_pad((string) $i, 5, '0', STR_PAD_LEFT),
+                'category' => 'Category ' . ($i % 10),
+                'address' => (object) [
+                    'street' => $i . ' Elm St',
+                    'city' => 'City ' . ($i % 50),
+                    'zip' => str_pad((string) ($i % 99999), 5, '0', STR_PAD_LEFT),
+                ],
+            ];
+            $this->allNull[] = (object) [
+                'id' => null,
+                'name' => null,
+                'description' => null,
+                'price' => null,
+                'quantity' => null,
+                'active' => null,
+                'sku' => null,
+                'category' => null,
+                'address' => null,
+            ];
+            $this->sparse[] = (object) [
+                'id' => $i,
+                'address' => (object) ['city' => 'City ' . ($i % 50)],
+            ];
+        }
+    }
+
+    #[Revs(100)]
+    #[Groups(['literal', 'x1', 'sparse'])]
+    public function benchOptionalAllPresent_x1(): void
+    {
+        $this->optionalDriver->encode('test', [$this->allPresent[0]]);
+    }
+
+    #[Groups(['literal', 'x500', 'sparse'])]
+    public function benchOptionalAllPresent_x500(): void
+    {
+        foreach ($this->allPresent as $item) {
+            $this->optionalDriver->encode('test', [$item]);
+        }
+    }
+
+    #[Revs(100)]
+    #[Groups(['literal', 'x1', 'sparse'])]
+    public function benchOptionalAllNull_x1(): void
+    {
+        $this->optionalDriver->encode('test', [$this->allNull[0]]);
+    }
+
+    #[Groups(['literal', 'x500', 'sparse'])]
+    public function benchOptionalAllNull_x500(): void
+    {
+        foreach ($this->allNull as $item) {
+            $this->optionalDriver->encode('test', [$item]);
+        }
+    }
+
+    #[Revs(100)]
+    #[Groups(['literal', 'x1', 'sparse'])]
+    public function benchOptionalSparse_x1(): void
+    {
+        $this->optionalDriver->encode('test', [$this->sparse[0]]);
+    }
+
+    #[Groups(['literal', 'x500', 'sparse'])]
+    public function benchOptionalSparse_x500(): void
+    {
+        foreach ($this->sparse as $item) {
+            $this->optionalDriver->encode('test', [$item]);
+        }
+    }
+}
diff --git a/composer.json b/composer.json
@@ -34,8 +34,8 @@
         "php-standard-library/str": "^6.1",
         "php-standard-library/type": "^6.1",
         "php-standard-library/vec": "^6.1",
-        "veewee/reflecta": "^1.1",
-        "veewee/xml": "^4.10",
+        "veewee/reflecta": "^1.2",
+        "veewee/xml": "^4.14",
         "php-soap/engine": "^2.21",
         "php-soap/wsdl": "^1.19",
         "php-soap/xml": "^1.10",
@@ -53,8 +53,8 @@
         "phpbench/phpbench": "^1.6"
     },
     "scripts": {
-        "test:throws": "@php -d xdebug.mode=develop vendor/bin/phpunit --group no-throws --fail-on-skipped",
-        "throws:report": "@php -d xdebug.mode=develop vendor/bin/phpunit --no-progress --no-results --do-not-fail-on-risky --extension 'Soap\\Encoding\\Test\\Support\\Throws\\ThrowAttributionExtension'"
+        "test:throws": "@php -d xdebug.mode=develop -d zend.exception_ignore_args=1 vendor/bin/phpunit --group no-throws --fail-on-skipped",
+        "throws:report": "@php -d xdebug.mode=develop -d zend.exception_ignore_args=1 vendor/bin/phpunit --no-progress --no-results --do-not-fail-on-risky --extension 'Soap\\Encoding\\Test\\Support\\Throws\\ThrowAttributionExtension'"
     },
     "config": {
         "allow-plugins": {

diff --git a/src/Encoder/ObjectAccess.php b/src/Encoder/ObjectAccess.php
@@ -32,6 +32,7 @@ final class ObjectAccess
      * @param bool $isAnyPropertyQualified Whether at least one property is namespace qualified.
      * @param array<string, bool> $isAttribute Whether the property is an XML attribute instead of a child element.
      * @param array<string, list<never>|null> $decodeDefaultValues The value a property decodes to when its element is missing from the XML.
+     * @param array<string, bool> $omitWhenAbsent Whether encoding leaves the element out, instead of writing xsi:nil, when the property is absent from the PHP value.
      */
     public function __construct(
         public readonly array $properties,
@@ -41,6 +42,7 @@ public function __construct(
         public readonly bool  $isAnyPropertyQualified,
         public readonly array $isAttribute,
         public readonly array $decodeDefaultValues,
+        public readonly array $omitWhenAbsent,
     ) {
     }
 
@@ -86,6 +88,7 @@ private static function build(Context $context): self
         $isos = [];
         $isAttribute = [];
         $decodeDefaultValues = [];
+        $omitWhenAbsent = [];
         $isAnyPropertyQualified = false;
 
         foreach ($sortedProperties as $property) {
@@ -99,13 +102,14 @@ private static function build(Context $context): self
             $shouldLensBeOptional = self::shouldLensBeOptional($propertyTypeMeta);
             $normalizedProperties[$normalizedName] = $property;
 
-            $encoderLenses[$normalizedName] = self::createCustomEncoderLens($shouldLensBeOptional, $encoder, $type, $property)
-                ?? optional_property($normalizedName);
+            $customEncoderLens = self::createCustomEncoderLens($shouldLensBeOptional, $encoder, $type, $property);
+            $encoderLenses[$normalizedName] = $customEncoderLens ?? optional_property($normalizedName);
             $decoderLenses[$normalizedName] = self::createCustomDecoderLens($shouldLensBeOptional, $encoder, $type, $property)
                 ?? optional_index($name);
             $isos[$normalizedName] = $encoder->iso($propertyContext);
             $isAttribute[$normalizedName] = $propertyTypeMeta->isAttribute()->unwrapOr(false);
             $decodeDefaultValues[$normalizedName] = $propertyTypeMeta->isList()->unwrapOr(false) ? [] : null;
+            $omitWhenAbsent[$normalizedName] = $customEncoderLens === null && self::mayBeAbsent($name, $propertyTypeMeta);
 
             $isAnyPropertyQualified = $isAnyPropertyQualified || $propertyTypeMeta->isQualified()->unwrapOr(false);
         }
@@ -118,9 +122,22 @@ private static function build(Context $context): self
             $isAnyPropertyQualified,
             $isAttribute,
             $decodeDefaultValues,
+            $omitWhenAbsent,
         );
     }
 
+    /**
+     * Null and absent only encode differently for an optional nillable element: null writes xsi:nil, absent writes nothing.
+     * Every other element, attribute and the '_' text value encodes null and absent the same way.
+     */
+    private static function mayBeAbsent(string $propertyName, TypeMeta $meta): bool
+    {
+        return $propertyName !== '_'
+            && !$meta->isAttribute()->unwrapOr(false)
+            && $meta->isNil()->unwrapOr(false)
+            && $meta->minOccurs()->unwrapOr(1) === 0;
+    }
+
     /**
      * @return LensInterface<object|null, object|null, mixed, mixed>|null
      */

diff --git a/src/Encoder/ObjectEncoder.php b/src/Encoder/ObjectEncoder.php
@@ -15,6 +15,7 @@
 use function is_array;
 use function Psl\Fun\lazy;
 use function VeeWee\Reflecta\Iso\object_data;
+use function VeeWee\Reflecta\Reflect\property_is_initialized;
 use function VeeWee\Xml\Writer\Builder\children as writeChildren;
 use function VeeWee\Xml\Writer\Builder\raw;
 use function VeeWee\Xml\Writer\Builder\value as buildValue;
@@ -70,9 +71,8 @@ function (string|Element $value) use ($context, $objectAccess) : object {
      */
     private function to(Context $context, ObjectAccess $objectAccess, object|array $data): string
     {
-        if (is_array($data)) {
-            $data = (object) $data;
-        }
+        /** @var object $data */
+        $data = is_array($data) ? (object) $data : $data;
         $defaultAction = writeChildren([]);
 
         $children = [
@@ -89,6 +89,13 @@ private function to(Context $context, ObjectAccess $objectAccess, object|array $
                 $objectAccess->encoderLenses[$normalizePropertyName],
                 $data
             );
+            if ($value === null
+                && $objectAccess->omitWhenAbsent[$normalizePropertyName]
+                && !property_is_initialized($data, $normalizePropertyName)
+            ) {
+                continue;
+            }
+
             $iso = $objectAccess->isos[$normalizePropertyName];
 
             $children[] = match(true) {

diff --git a/src/Encoder/OptionalElementEncoder.php b/src/Encoder/OptionalElementEncoder.php
@@ -16,8 +16,9 @@
 /**
  * @template T of mixed
  * @implements XmlEncoder<T, T, string, ElementList|Element|string>
+ * @implements Feature\DecoratingEncoder<T, T, string|null, ElementList|Element|string|null>
  */
-final class OptionalElementEncoder implements Feature\ElementAware, Feature\OptionalAware, XmlEncoder
+final class OptionalElementEncoder implements Feature\DecoratingEncoder, Feature\ElementAware, Feature\OptionalAware, XmlEncoder
 {
     /**
      * @param XmlEncoder<T, T, string|null, ElementList|Element|string|null> $elementEncoder
@@ -27,6 +28,14 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @return XmlEncoder<T, T, string|null, ElementList|Element|string|null>
+     */
+    public function decoratedEncoder(): XmlEncoder
+    {
+        return $this->elementEncoder;
+    }
+
     /**
      * @return IsoInterface<T, T, string, ElementList|Element|string>
      */

diff --git a/src/Encoder/RepeatingElementEncoder.php b/src/Encoder/RepeatingElementEncoder.php
@@ -13,8 +13,9 @@
 /**
  * @template T
  * @implements XmlEncoder<iterable<array-key, T>|null, iterable<array-key, T>, string, Element|ElementList|string>
+ * @implements Feature\DecoratingEncoder<T, T, string|null, Element|ElementList|string|null>
  */
-final class RepeatingElementEncoder implements Feature\ElementAware, Feature\ListAware, XmlEncoder
+final class RepeatingElementEncoder implements Feature\DecoratingEncoder, Feature\ElementAware, Feature\ListAware, XmlEncoder
 {
     /**
      * @param XmlEncoder<T, T, string|null, Element|ElementList|string|null> $typeEncoder
@@ -24,6 +25,14 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @return XmlEncoder<T, T, string|null, Element|ElementList|string|null>
+     */
+    public function decoratedEncoder(): XmlEncoder
+    {
+        return $this->typeEncoder;
+    }
+
     /**
      * @return Iso<iterable<array-key, T>|null, iterable<array-key, T>, string, Element|ElementList|string>
      */

diff --git a/src/Encoder/XsiTypeEncoder.php b/src/Encoder/XsiTypeEncoder.php
@@ -11,8 +11,9 @@
 
 /**
  * @implements XmlEncoder<mixed, mixed, string, Element|string>
+ * @implements Feature\DecoratingEncoder<mixed, mixed, string|null, Element|ElementList|string|null>
  */
-final readonly class XsiTypeEncoder implements Feature\ElementAware, XmlEncoder
+final readonly class XsiTypeEncoder implements Feature\DecoratingEncoder, Feature\ElementAware, XmlEncoder
 {
     /**
      * @param XmlEncoder<mixed, mixed, string|null, Element|ElementList|string|null> $encoder
@@ -22,6 +23,14 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @return XmlEncoder<mixed, mixed, string|null, Element|ElementList|string|null>
+     */
+    public function decoratedEncoder(): XmlEncoder
+    {
+        return $this->encoder;
+    }
+
     /**
      * @return Iso<mixed, mixed, string, Element|string>
      */