added file support

Author: eceltov

app/V1Module/presenters/UploadedFilesPresenter.php

@@ -2,9 +2,11 @@
 
 namespace App\V1Module\Presenters;
 
+use App\Helpers\MetaFormats\Attributes\File;
 use App\Helpers\MetaFormats\Attributes\Post;
 use App\Helpers\MetaFormats\Attributes\Query;
 use App\Helpers\MetaFormats\Attributes\Path;
+use App\Helpers\MetaFormats\FileRequestType;
 use App\Helpers\MetaFormats\Validators\VInt;
 use App\Helpers\MetaFormats\Validators\VString;
 use App\Helpers\MetaFormats\Validators\VUuid;
@@ -321,6 +323,7 @@ public function checkUpload()
      * @throws CannotReceiveUploadedFileException
      * @throws InternalServerException
      */
+    #[File(FileRequestType::FormData, "The whole file to be uploaded")]
     public function actionUpload()
     {
         $user = $this->getCurrentUser();
@@ -440,6 +443,7 @@ public function checkAppendPartial(string $id)
      */
     #[Query("offset", new VInt(), "Offset of the chunk for verification", required: true)]
     #[Path("id", new VUuid(), "Identifier of the partial file", required: true)]
+    #[File(FileRequestType::OctetStream, "A chunk of the uploaded file")]
     public function actionAppendPartial(string $id, int $offset)
     {
         $partialFile = $this->uploadedPartialFiles->findOrThrow($id);

app/V1Module/presenters/base/BasePresenter.php

@@ -305,6 +305,8 @@ private function getValueFromParamData(RequestParamData $paramData): mixed
                 return $this->getQueryField($paramData->name, required: $paramData->required);
             case Type::Path:
                 return $this->getPathField($paramData->name);
+            case Type::File:
+                return $this->getFileField(required: $paramData->required);
             default:
                 throw new InternalServerException("Unknown parameter type: {$paramData->type->name}");
         }
@@ -338,6 +340,25 @@ private function getPostField($param, $required = true)
         }
     }
 
+    private function getFileField($required = true)
+    {
+        $req = $this->getRequest();
+        $files = $req->getFiles();
+
+        if (count($files) === 0) {
+            if ($required) {
+                throw new BadRequestException("No file was uploaded");
+            } else {
+                return null;
+            }
+        } elseif (count($files) > 1) {
+            throw new BadRequestException("Too many files were uploaded");
+        }
+
+        $file = array_pop($files);
+        return $file;
+    }
+
     private function getQueryField($param, $required = true)
     {
         $value = $this->getRequest()->getParameter($param);

app/helpers/MetaFormats/Attributes/FFile.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Attributes;
+
+use App\Helpers\MetaFormats\FileRequestType;
+use App\Helpers\MetaFormats\Type;
+use App\Helpers\MetaFormats\Validators\VFile;
+use Attribute;
+
+/**
+ * Attribute used to annotate format definition properties representing a file parameter.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class FFile extends FormatParameterAttribute
+{
+    /**
+     * @param FileRequestType $fileRequestType How will the file be transmitted in the request.
+     * @param string $description The description of the request parameter.
+     * @param bool $required Whether the request parameter is required.
+     */
+    public function __construct(
+        FileRequestType $fileRequestType,
+        string $description = "",
+        bool $required = true,
+    ) {
+        parent::__construct(Type::File, new VFile($fileRequestType), $description, $required, false);
+    }
+}

app/helpers/MetaFormats/Attributes/File.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Attributes;
+
+use App\Helpers\MetaFormats\FileRequestType;
+use App\Helpers\MetaFormats\Type;
+use App\Helpers\MetaFormats\Validators\VFile;
+use Attribute;
+
+/**
+ * Attribute used to specify that an endpoint expects a file.
+ */
+#[Attribute(Attribute::TARGET_METHOD)]
+class File extends Param
+{
+    /**
+     * @param FileRequestType $fileRequestType How will the file be transmitted in the request.
+     * @param string $description The description of the request parameter.
+     * @param bool $required Whether the request parameter is required.
+     */
+    public function __construct(
+        FileRequestType $fileRequestType,
+        string $description = "",
+        bool $required = true,
+    ) {
+        parent::__construct(Type::File, "file", new VFile($fileRequestType), $description, $required, false);
+    }
+}

app/helpers/MetaFormats/FileRequestType.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Helpers\MetaFormats;
+
+// @codingStandardsIgnoreStart
+/**
+ * An enumeration of types how files can be transmitted.
+ */
+enum FileRequestType
+{
+  case OctetStream;
+  case FormData;
+}
+// @codingStandardsIgnoreEnd

app/helpers/MetaFormats/MetaFormatHelper.php

@@ -3,6 +3,8 @@
 namespace App\Helpers\MetaFormats;
 
 use App\Exceptions\InternalServerException;
+use App\Helpers\MetaFormats\Attributes\FFile;
+use App\Helpers\MetaFormats\Attributes\File;
 use App\Helpers\MetaFormats\Attributes\Format;
 use App\Helpers\MetaFormats\Attributes\FormatParameterAttribute;
 use App\Helpers\MetaFormats\Attributes\FPath;
@@ -50,8 +52,9 @@ public static function getEndpointAttributes(ReflectionMethod $reflectionMethod)
         $path = $reflectionMethod->getAttributes(name: Path::class);
         $query = $reflectionMethod->getAttributes(name: Query::class);
         $post = $reflectionMethod->getAttributes(name: Post::class);
+        $file = $reflectionMethod->getAttributes(name: File::class);
         $param = $reflectionMethod->getAttributes(name: Param::class);
-        return array_merge($path, $query, $post, $param);
+        return array_merge($path, $query, $post, $file, $param);
     }
 
     /**
@@ -91,7 +94,14 @@ public static function extractFormatParameterData(ReflectionProperty $reflection
         $pathAttributes = $reflectionObject->getAttributes(FPath::class);
         $queryAttributes = $reflectionObject->getAttributes(FQuery::class);
         $postAttributes = $reflectionObject->getAttributes(FPost::class);
-        $requestAttributes = array_merge($longAttributes, $pathAttributes, $queryAttributes, $postAttributes);
+        $fileAttributes = $reflectionObject->getAttributes(FFile::class);
+        $requestAttributes = array_merge(
+            $longAttributes,
+            $pathAttributes,
+            $queryAttributes,
+            $postAttributes,
+            $fileAttributes
+        );
 
         // there should be only one attribute
         if (count($requestAttributes) == 0) {

app/helpers/MetaFormats/RequestParamData.php

@@ -6,6 +6,7 @@
 use App\Exceptions\InvalidApiArgumentException;
 use App\Helpers\MetaFormats\Validators\BaseValidator;
 use App\Helpers\MetaFormats\Validators\VArray;
+use App\Helpers\MetaFormats\Validators\VFile;
 use App\Helpers\MetaFormats\Validators\VObject;
 use App\Helpers\Swagger\AnnotationParameterData;
 
@@ -143,6 +144,12 @@ public function toAnnotationParameterData()
             }, $nestedRequestParmData);
         }
 
+        // get file request type if file
+        $fileRequestType = null;
+        if ($this->validators[0] instanceof VFile) {
+            $fileRequestType = $this->validators[0]->fileRequestType;
+        }
+
         return new AnnotationParameterData(
             $swaggerType,
             $this->name,
@@ -155,6 +162,7 @@ public function toAnnotationParameterData()
             $arrayDepth,
             $nestedObjectParameterData,
             $constraints,
+            $fileRequestType,
         );
     }
 }

app/helpers/MetaFormats/Type.php

@@ -11,5 +11,6 @@ enum Type
   case Post;
   case Query;
   case Path;
+  case File;
 }
 // @codingStandardsIgnoreEnd

app/helpers/MetaFormats/Validators/VFile.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Validators;
+
+use App\Helpers\MetaFormats\FileRequestType;
+
+/**
+ * Validates files. Currently, all files are valid.
+ */
+class VFile extends BaseValidator
+{
+    public const SWAGGER_TYPE = "string";
+    public readonly FileRequestType $fileRequestType;
+
+    public function __construct(FileRequestType $fileRequestType)
+    {
+        parent::__construct(strict: false);
+        $this->fileRequestType = $fileRequestType;
+    }
+
+    public function validate(mixed $value): bool
+    {
+        return true;
+    }
+}