string validator constraints are now propagated to the swagger document

Author: eceltov

app/helpers/MetaFormats/RequestParamData.php

@@ -122,6 +122,16 @@ public function toAnnotationParameterData()
         // get example value from the first validator
         $exampleValue = $this->validators[0]->getExampleValue();
 
+        // get constraints from validators
+        $constraints = null;
+        foreach ($this->validators as $validator) {
+            $constraints = $validator->getConstraints();
+            // it is assumed that at most one validator defines constraints
+            if ($constraints !== null) {
+                break;
+            }
+        }
+
         // add nested parameter data if this is an object
         $format = $this->getFormatName();
         $nestedObjectParameterData = null;
@@ -142,6 +152,7 @@ public function toAnnotationParameterData()
             $exampleValue,
             $nestedArraySwaggerType,
             $nestedObjectParameterData,
+            $constraints,
         );
     }
 }

app/helpers/MetaFormats/Validators/BaseValidator.php

@@ -2,6 +2,8 @@
 
 namespace App\Helpers\MetaFormats\Validators;
 
+use App\Helpers\Swagger\ParameterConstraints;
+
 /**
  * Base class for all validators.
  */
@@ -43,6 +45,16 @@ public function getExampleValue(): string | null
         return null;
     }
 
+    /**
+     * @return ParameterConstraints Returns all parameter constrains that will be written into the generated
+     *  swagger document. Returns null if there are no constraints.
+     */
+    public function getConstraints(): ?ParameterConstraints
+    {
+        // there are no default constraints
+        return null;
+    }
+
     /**
      * Validates a value with the configured validation strictness.
      * @param mixed $value The value to be validated.

app/helpers/MetaFormats/Validators/VString.php

@@ -2,6 +2,8 @@
 
 namespace App\Helpers\MetaFormats\Validators;
 
+use App\Helpers\Swagger\ParameterConstraints;
+
 /**
  * Validates strings.
  */
@@ -32,6 +34,14 @@ public function getExampleValue(): string
         return "text";
     }
 
+    public function getConstraints(): ParameterConstraints
+    {
+        // do not pass redundant constraints
+        $minLength = ($this->minLength > 0 ? $this->minLength : null);
+        $maxLength = ($this->maxLength !== -1 ? $this->maxLength : null);
+        return new ParameterConstraints($this->regex, $minLength, $maxLength);
+    }
+
     public function validate(mixed $value): bool
     {
         // do not allow other types

app/helpers/Swagger/AnnotationParameterData.php

@@ -19,6 +19,7 @@ class AnnotationParameterData
     public ?string $example;
     public ?string $nestedArraySwaggerType;
     public ?array $nestedObjectParameterData;
+    public ?ParameterConstraints $constraints;
 
     public function __construct(
         string $swaggerType,
@@ -27,9 +28,10 @@ public function __construct(
         string $location,
         bool $required,
         bool $nullable,
-        string $example = null,
-        string $nestedArraySwaggerType = null,
+        ?string $example = null,
+        ?string $nestedArraySwaggerType = null,
         ?array $nestedObjectParameterData = null,
+        ?ParameterConstraints $constraints = null,
     ) {
         $this->swaggerType = $swaggerType;
         $this->name = $name;
@@ -40,10 +42,12 @@ public function __construct(
         $this->example = $example;
         $this->nestedArraySwaggerType = $nestedArraySwaggerType;
         $this->nestedObjectParameterData = $nestedObjectParameterData;
+        $this->constraints = $constraints;
     }
 
     private function addArrayItemsIfArray(ParenthesesBuilder $container)
     {
+        ///TODO: nested constraints should be added here
         if ($this->swaggerType !== "array") {
             return;
         }
@@ -128,6 +132,9 @@ public function toPropertyAnnotation(): string
             $body->addKeyValue("description", $this->description);
         }
 
+        // handle param constraints
+        $this->constraints?->addConstraints($body);
+
         // handle arrays
         $this->addArrayItemsIfArray($body);
 

app/helpers/Swagger/ParameterConstraints.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Helpers\Swagger;
+
+class ParameterConstraints
+{
+  private array $constraints;
+  
+  /**
+   * Constructs a container for swagger constraints.
+   * Constructor parameter names match swagger keywords, see
+   * https://swagger.io/docs/specification/v3_0/data-models/keywords/.
+   * @param ?string $pattern String regex pattern.
+   * @param ?int $minLength String min length.
+   * @param ?int $maxLength String max length.
+   */
+  public function __construct(?string $pattern = null, ?int $minLength = null, ?int $maxLength = null)
+  {
+    $this->constraints["pattern"] = $pattern;
+    $this->constraints["minLength"] = $minLength;
+    $this->constraints["maxLength"] = $maxLength;
+  }
+
+  /**
+   * Adds constraints to a ParenthesesBuilder for swagger doc construction.
+   * @param \App\Helpers\Swagger\ParenthesesBuilder $container The container for keywords and values.
+   */
+  public function addConstraints(ParenthesesBuilder $container)
+  {
+    foreach ($this->constraints as $keyword=>$value) {
+      // skip null values
+      if ($value === null) {
+        continue;
+      }
+
+      $container->addKeyValue($keyword, $value);
+    }
+  }
+}