Implement required properties mapping

README.md

@@ -90,6 +90,40 @@ $request = $decoder->decode(/** protobuf buffer here */, CreateUserRequest::clas
 echo $request->name;
 ```
 
+### Required fields
+
+`Reflector::map()` maps missing fields using property defaults when they exist.
+If a property is non-nullable and has no default value, it is treated as required.
+
+When one or more required properties are missing, decoding fails with `Thesis\Protobuf\Reflection\Exception\MappingError`.
+The exception contains all reasons in `->reasons` (each reason is typically `PropertyRequired`).
+
+This behavior is aligned with other protobuf implementations/plugins: messages missing required fields are treated as invalid during decode.
+
+A field is considered required when either:
+- it is defined as `required` in `proto2`;
+- it is defined in editions with `features.field_presence = LEGACY_REQUIRED`.
+
+```php
+use Thesis\Protobuf\Decoder;
+use Thesis\Protobuf\Reflection;
+
+$decoder = Decoder\Builder::buildDefault();
+
+try {
+    $message = $decoder->decode($buffer, CreateUserRequest::class);
+} catch (Reflection\Exception\MappingError $e) {
+    foreach ($e->reasons as $reason) {
+        if ($reason instanceof Reflection\Exception\PropertyRequired) {
+            echo $reason->class . "::$" . $reason->property . PHP_EOL;
+        }
+    }
+}
+```
+
+Both `Encoder::encode()` and `Decoder::decode()` throw `Thesis\Protobuf\ProtobufException`.
+Domain protobuf exceptions are preserved and are not wrapped into generic runtime errors.
+
 ### Unknown fields
 
 When a protobuf message is decoded, it may contain fields that are not defined in the target class.

src/Decoder.php

@@ -4,8 +4,6 @@
 
 namespace Thesis\Protobuf;
 
-use Thesis\Protobuf\Decoder\DecodingError;
-
 /**
  * @api
  */
@@ -15,7 +13,7 @@ interface Decoder
      * @template T of object
      * @param class-string<T> $classType
      * @return T
-     * @throws DecodingError
+     * @throws ProtobufException
      */
     public function decode(string $buffer, string $classType): object;
 }

src/Decoder/Internal/ReflectionDecoder.php

@@ -5,6 +5,7 @@
 namespace Thesis\Protobuf\Decoder\Internal;
 
 use Thesis\Protobuf\Decoder;
+use Thesis\Protobuf\ProtobufException;
 use Thesis\Protobuf\Reflection\Reflector;
 use Thesis\Protobuf\Serializer;
 
@@ -29,6 +30,8 @@ public function decode(string $buffer, string $classType): object
                 ),
                 $classType,
             );
+        } catch (ProtobufException $e) {
+            throw $e;
         } catch (\Throwable $e) {
             throw new Decoder\DecodingError($e->getMessage(), (int) $e->getCode(), $e);
         }

src/Encoder.php

@@ -4,15 +4,13 @@
 
 namespace Thesis\Protobuf;
 
-use Thesis\Protobuf\Encoder\EncodingError;
-
 /**
  * @api
  */
 interface Encoder
 {
     /**
-     * @throws EncodingError
+     * @throws ProtobufException
      */
     public function encode(object $message): string;
 }

src/Encoder/Internal/ReflectionEncoder.php

@@ -5,6 +5,7 @@
 namespace Thesis\Protobuf\Encoder\Internal;
 
 use Thesis\Protobuf\Encoder;
+use Thesis\Protobuf\ProtobufException;
 use Thesis\Protobuf\Reflection\Reflector;
 use Thesis\Protobuf\Serializer;
 
@@ -25,6 +26,8 @@ public function encode(object $message): string
             return $this->serializer->serialize(
                 $this->reflector->message($message),
             );
+        } catch (ProtobufException $e) {
+            throw $e;
         } catch (\Throwable $e) {
             throw new Encoder\EncodingError($e->getMessage(), (int) $e->getCode(), $e);
         }

src/Reflection/Exception/MappingError.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Thesis\Protobuf\Reflection\Exception;
+
+use Thesis\Protobuf\Reflection\ReflectionException;
+
+/**
+ * @api
+ */
+final class MappingError extends ReflectionException
+{
+    /**
+     * @param non-empty-list<ReflectionException> $reasons
+     */
+    public function __construct(
+        public readonly array $reasons,
+    ) {
+        parent::__construct(\sprintf(
+            'Multiple exceptions encountered (%d): %s',
+            \count($reasons),
+            implode('', array_map(
+                static fn(ReflectionException $reason) => \sprintf("\n\n%s: %s", $reason::class, $reason->getMessage()),
+                $this->reasons,
+            )),
+        ));
+    }
+}

src/Reflection/Exception/PropertyRequired.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Thesis\Protobuf\Reflection\Exception;
+
+use Thesis\Protobuf\Reflection\ReflectionException;
+
+/**
+ * @api
+ */
+final class PropertyRequired extends ReflectionException
+{
+    /**
+     * @param non-empty-string $class
+     * @param non-empty-string $property
+     */
+    public function __construct(
+        public readonly string $class,
+        public readonly string $property,
+    ) {
+        parent::__construct(\sprintf('The property "%s::$%s" is required and cannot be initialized implicitly.', $class, $property));
+    }
+}

src/Reflection/ReflectionException.php

@@ -4,7 +4,9 @@
 
 namespace Thesis\Protobuf\Reflection;
 
+use Thesis\Protobuf\ProtobufException;
+
 /**
  * @api
  */
-abstract class ReflectionException extends \Exception {}
+abstract class ReflectionException extends ProtobufException {}