added shorthands for format parameter attributes

Author: eceltov

app/V1Module/presenters/RegistrationPresenter.php

@@ -34,7 +34,7 @@
 use App\Helpers\EmailVerificationHelper;
 use App\Helpers\RegistrationConfig;
 use App\Helpers\InvitationHelper;
-use App\Helpers\MetaFormats\Attributes\FormatAttribute;
+use App\Helpers\MetaFormats\Attributes\Format;
 use App\Helpers\MetaFormats\FormatDefinitions\UserFormat;
 use App\Helpers\MetaFormats\Attributes\ParamAttribute;
 use App\Security\Roles;
@@ -274,19 +274,7 @@ public function checkCreateInvitation()
      * @throws BadRequestException
      * @throws InvalidArgumentException
      */
-    #[Post("email", new VEmail(), "An email that will serve as a login name")]
-    #[Post("firstName", new VString(2), "First name", required: true)]
-    #[Post("lastName", new VString(2), "Last name")]
-    #[Post("instanceId", new VString(1), "Identifier of the instance to register in")]
-    #[Post("titlesBeforeName", new VString(1), "Titles which is placed before user name", required: false)]
-    #[Post("titlesAfterName", new VString(1), "Titles which is placed after user name", required: false)]
-    #[Post(
-        "groups",
-        new VArray(),
-        "List of group IDs in which the user is added right after registration",
-        required: false,
-    )]
-    #[Post("locale", new VString(2, 2), "Language used in the invitation email (en by default).", required: false)]
+    #[Format(UserFormat::class)]
     public function actionCreateInvitation()
     {
         $req = $this->getRequest();

app/helpers/MetaFormats/Attributes/FPath.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Attributes;
+
+use App\Helpers\MetaFormats\Type;
+use Attribute;
+
+/**
+ * Attribute used to annotate format definition properties.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class FPath extends FormatParameterAttribute
+{
+    /**
+     * @param mixed $validators A validator object or an array of validators applied to the request parameter.
+     * @param string $description The description of the request parameter.
+     * @param bool $required Whether the request parameter is required.
+     * @param bool $nullable Whether the request parameter can be null.
+     */
+    public function __construct(
+        mixed $validators,
+        string $description = "",
+        bool $required = true,
+        bool $nullable = false,
+    ) {
+        parent::__construct(Type::Path, $validators, $description, $required, $nullable);
+    }
+}

app/helpers/MetaFormats/Attributes/FPost.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Attributes;
+
+use App\Helpers\MetaFormats\Type;
+use Attribute;
+
+/**
+ * Attribute used to annotate format definition properties.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class FPost extends FormatParameterAttribute
+{
+    /**
+     * @param mixed $validators A validator object or an array of validators applied to the request parameter.
+     * @param string $description The description of the request parameter.
+     * @param bool $required Whether the request parameter is required.
+     * @param bool $nullable Whether the request parameter can be null.
+     */
+    public function __construct(
+        mixed $validators,
+        string $description = "",
+        bool $required = true,
+        bool $nullable = false,
+    ) {
+        parent::__construct(Type::Post, $validators, $description, $required, $nullable);
+    }
+}

app/helpers/MetaFormats/Attributes/FQuery.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Attributes;
+
+use App\Helpers\MetaFormats\Type;
+use Attribute;
+
+/**
+ * Attribute used to annotate format definition properties.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class FQuery extends FormatParameterAttribute
+{
+    /**
+     * @param mixed $validators A validator object or an array of validators applied to the request parameter.
+     * @param string $description The description of the request parameter.
+     * @param bool $required Whether the request parameter is required.
+     * @param bool $nullable Whether the request parameter can be null.
+     */
+    public function __construct(
+        mixed $validators,
+        string $description = "",
+        bool $required = true,
+        bool $nullable = false,
+    ) {
+        parent::__construct(Type::Query, $validators, $description, $required, $nullable);
+    }
+}

app/helpers/MetaFormats/Attributes/FormatAttribute.php

@@ -8,7 +8,7 @@
  * Attribute for format definitions and usings.
  */
 #[Attribute]
-class FormatAttribute
+class Format
 {
     public string $class;
 

app/helpers/MetaFormats/FormatDefinitions/GroupFormat.php

@@ -2,50 +2,39 @@
 
 namespace App\Helpers\MetaFormats\FormatDefinitions;
 
-use App\Helpers\MetaFormats\Attributes\FormatAttribute;
+use App\Helpers\MetaFormats\Attributes\Format;
 use App\Helpers\MetaFormats\MetaFormat;
 use App\Helpers\MetaFormats\Attributes\FormatParameterAttribute;
+use App\Helpers\MetaFormats\Attributes\FPost;
 use App\Helpers\MetaFormats\Type;
+use App\Helpers\MetaFormats\Validators\VArray;
 use App\Helpers\MetaFormats\Validators\VEmail;
 use App\Helpers\MetaFormats\Validators\VString;
 
-#[FormatAttribute(UserFormat::class)]
+#[Format(UserFormat::class)]
 class UserFormat extends MetaFormat
 {
-    #[FormatAttribute("email")]
-    #[FormatParameterAttribute(Type::Post, new VEmail(), "An email that will serve as a login name")]
-    public string $email;
+    #[FPost(new VEmail(), "An email that will serve as a login name")]
+    public ?string $email;
 
-    #[FormatParameterAttribute(Type::Post, new VString(), "First name")]
+    #[FPost(new VString(2), "First name", required: true)]
     public string $firstName;
 
-    #[FormatParameterAttribute(Type::Post, new VString(), "Last name")]
-    public string $lastName;
+    #[FPost(new VString(2), "Last name")]
+    public ?string $lastName;
 
-    #[FormatParameterAttribute(Type::Post, new VString(), "A password for authentication")]
-    public string $password;
+    #[FPost(new VString(1), "Identifier of the instance to register in")]
+    public ?string $instanceId;
 
-    #[FormatParameterAttribute(Type::Post, new VString(), "A password confirmation")]
-    public string $passwordConfirm;
-
-    #[FormatParameterAttribute(Type::Post, new VString(), "Identifier of the instance to register in")]
-    public string $instanceId;
-
-    #[FormatParameterAttribute(
-        Type::Post,
-        new VString(),
-        "Titles that are placed before user name",
-        required: false,
-        nullable: true
-    )]
+    #[FPost(new VString(1), "Titles that are placed before user name", required: false)]
     public ?string $titlesBeforeName;
 
-    #[FormatParameterAttribute(
-        Type::Post,
-        new VString(),
-        "Titles that are placed after user name",
-        required: false,
-        nullable: true
-    )]
+    #[FPost(new VString(1), "Titles that are placed after user name", required: false)]
     public ?string $titlesAfterName;
+
+    #[FPost(new VArray(), "List of group IDs in which the user is added right after registration", required: false)]
+    public ?array $groups;
+
+    #[FPost(new VString(2, 2), "Language used in the invitation email (en by default).", required: false)]
+    public ?string $locale;
 }

app/helpers/MetaFormats/FormatDefinitions/UserFormat.php

@@ -3,8 +3,11 @@
 namespace App\Helpers\MetaFormats;
 
 use App\Exceptions\InternalServerException;
-use App\Helpers\MetaFormats\Attributes\FormatAttribute;
+use App\Helpers\MetaFormats\Attributes\Format;
 use App\Helpers\MetaFormats\Attributes\FormatParameterAttribute;
+use App\Helpers\MetaFormats\Attributes\FPath;
+use App\Helpers\MetaFormats\Attributes\FPost;
+use App\Helpers\MetaFormats\Attributes\FQuery;
 use App\Helpers\MetaFormats\Attributes\Param;
 use App\Helpers\MetaFormats\Attributes\Path;
 use App\Helpers\MetaFormats\Attributes\Post;
@@ -45,15 +48,15 @@ public static function extractMethodCheckedParams(string $className, string $met
     }
 
     /**
-     * Checks whether an entity contains a FormatAttribute and extracts the format if so.
+     * Checks whether an entity contains a Format attribute and extracts the format if so.
      * @param \ReflectionClass|\ReflectionProperty|\ReflectionMethod $reflectionObject A reflection
      * object of the entity.
-     * @return ?string Returns the format or null if no FormatAttribute was present.
+     * @return ?string Returns the format or null if no Format attribute was present.
      */
     public static function extractFormatFromAttribute(
-        ReflectionClass|ReflectionProperty|ReflectionMethod $reflectionObject
+        ReflectionClass | ReflectionProperty | ReflectionMethod $reflectionObject
     ): ?string {
-        $formatAttributes = $reflectionObject->getAttributes(FormatAttribute::class);
+        $formatAttributes = $reflectionObject->getAttributes(Format::class);
         if (count($formatAttributes) === 0) {
             return null;
         }
@@ -100,11 +103,33 @@ public static function extractRequestParamData(ReflectionMethod $reflectionMetho
         return $data;
     }
 
-    public static function extractFormatParameterData(ReflectionProperty $reflectionObject): ?RequestParamData
+    /**
+     * Finds the format attribute of the property and extracts its data.
+     * @param \ReflectionProperty $reflectionObject The reflection object of the property.
+     * @throws \App\Exceptions\InternalServerException Thrown when there is not exactly one format attribute.
+     * @return RequestParamData Returns the data from the attribute.
+     */
+    public static function extractFormatParameterData(ReflectionProperty $reflectionObject): RequestParamData
     {
-        $requestAttributes = $reflectionObject->getAttributes(FormatParameterAttribute::class);
-        if (count($requestAttributes) === 0) {
-            return null;
+        // find all property attributes
+        $longAttributes = $reflectionObject->getAttributes(FormatParameterAttribute::class);
+        $pathAttribues = $reflectionObject->getAttributes(FPath::class);
+        $queryAttributes = $reflectionObject->getAttributes(FQuery::class);
+        $postAttributes = $reflectionObject->getAttributes(FPost::class);
+        $requestAttributes = array_merge($longAttributes, $pathAttribues, $queryAttributes, $postAttributes);
+
+        // there should be only one attribute
+        if (count($requestAttributes) == 0) {
+            throw new InternalServerException(
+                "The field {$reflectionObject->name} of "
+                    . "class {$reflectionObject->class} does not have a property attribute."
+            );
+        }
+        if (count($requestAttributes) > 1) {
+            throw new InternalServerException(
+                "The field {$reflectionObject->name} of "
+                    . "class {$reflectionObject->class} has more than one attribute."
+            );
         }
 
         $requestAttribute = $requestAttributes[0]->newInstance();
@@ -142,18 +167,12 @@ public static function debugGetAttributes(
    */
     public static function createNameToFieldDefinitionsMap(string $className): array
     {
-        $class = new ReflectionClass($className);
+        $class = new ReflectionClass(objectOrClass: $className);
         $fields = get_class_vars($className);
         $formats = [];
         foreach ($fields as $fieldName => $value) {
             $field = $class->getProperty($fieldName);
             $requestParamData = self::extractFormatParameterData($field);
-            if ($requestParamData === null) {
-                throw new InternalServerException(
-                    "The field $fieldName of class $className does not have a RequestAttribute."
-                );
-            }
-
             $formats[$fieldName] = $requestParamData;
         }