From 4eec51c0afac59defdc9cef511959f6667285a8d Mon Sep 17 00:00:00 2001
From: Leo Bedrosian <leo.bedrosian@madwire.com>
Date: Mon, 23 Sep 2024 17:07:50 -0500
Subject: [PATCH] Added explanation text to clarify the purpose.

---
 .../BodyValidator/MultipartValidator.php        | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/PSR7/Validators/BodyValidator/MultipartValidator.php b/src/PSR7/Validators/BodyValidator/MultipartValidator.php
index 8220b900..0c1621dc 100644
--- a/src/PSR7/Validators/BodyValidator/MultipartValidator.php
+++ b/src/PSR7/Validators/BodyValidator/MultipartValidator.php
@@ -291,6 +291,23 @@ private function validateServerRequestMultipart(
 
         $files = $this->normalizeFiles($message->getUploadedFiles());
 
+        // The PHP kernel separates file data (binary) from body data so it's
+        // imperative to combine the two arrays __recursively__ to have properly
+        // constructed arrays of objects (collections) prior to validating
+        // them against the schema
+        //
+        // Otherwise, the file array will overwrite the body array at the common
+        // __root__ element, which may result in an object validation error if
+        // the object also contains other properties (stored in the body array)
+        //
+        // Eg: Array of file objects with a text descriptor
+        // [
+        //   ['description' => <string>, 'file' => <binary>]
+        //   ['description' => <string>, 'file' => <binary>]
+        //   ['description' => <string>, 'file' => <binary>]
+        // ]
+        //
+        // The 'description' would be in $body and 'file' would be in $files
         $body = array_replace_recursive($body, $files);
 
         $validator = new SchemaValidator($this->detectValidationStrategy($message));