Merge #684

684: Improve coding standards r=curquiza a=norkunas

# Pull Request

## Related issue
Fixes #<issue_number>

## What does this PR do?
- Add missing phpdocs;
- Replace `DateTime` with `DateTimeinterface` to encourage usage of `DateTimeImmutable`;
- Add more tests for contracts;
- Make tests a little bit more consistent;
- Add missing php typehints;

## PR checklist
Please check if your PR fulfills the following requirements:
- [ ] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?



Co-authored-by: Tomas <norkunas.tom@gmail.com>

src/Contracts/DeleteTasksQuery.php

@@ -10,9 +10,17 @@ class DeleteTasksQuery
 {
     use TasksQueryTrait;
 
-    private array $canceledBy;
-
-    public function setCanceledBy(array $canceledBy)
+    /**
+     * @var non-empty-list<int>|null
+     */
+    private ?array $canceledBy = null;
+
+    /**
+     * @param non-empty-list<int> $canceledBy
+     *
+     * @return $this
+     */
+    public function setCanceledBy(array $canceledBy): self
     {
         $this->canceledBy = $canceledBy;
 
@@ -24,8 +32,8 @@ public function toArray(): array
         return array_filter(
             array_merge(
                 $this->baseArray(),
-                ['canceledBy' => $this->formatArray($this->canceledBy ?? null)]
-            ), function ($item) { return null != $item || is_numeric($item); }
+                ['canceledBy' => $this->formatArray($this->canceledBy)]
+            ), static function ($item) { return null !== $item; }
         );
     }
 }

src/Contracts/DocumentsQuery.php

@@ -6,27 +6,58 @@
 
 class DocumentsQuery
 {
-    private int $offset;
-    private int $limit;
-    private array $fields;
-    private array $filter;
+    /**
+     * @var non-negative-int|null
+     */
+    private ?int $offset = null;
+
+    /**
+     * @var non-negative-int|null
+     */
+    private ?int $limit = null;
+
+    /**
+     * @var non-empty-list<string>|null
+     */
+    private ?array $fields = null;
+
+    /**
+     * @var list<non-empty-string|list<non-empty-string>>|null
+     */
+    private ?array $filter = null;
+
     private ?bool $retrieveVectors = null;
 
-    public function setOffset(int $offset): DocumentsQuery
+    /**
+     * @param non-negative-int $offset
+     *
+     * @return $this
+     */
+    public function setOffset(int $offset): self
     {
         $this->offset = $offset;
 
         return $this;
     }
 
-    public function setLimit(int $limit): DocumentsQuery
+    /**
+     * @param non-negative-int $limit
+     *
+     * @return $this
+     */
+    public function setLimit(int $limit): self
     {
         $this->limit = $limit;
 
         return $this;
     }
 
-    public function setFields(array $fields): DocumentsQuery
+    /**
+     * @param non-empty-list<string> $fields
+     *
+     * @return $this
+     */
+    public function setFields(array $fields): self
     {
         $this->fields = $fields;
 
@@ -38,9 +69,9 @@ public function setFields(array $fields): DocumentsQuery
      *
      * @param list<non-empty-string|list<non-empty-string>> $filter a filter expression written as an array of strings
      *
-     * @return DocumentsQuery the updated DocumentsQuery instance
+     * @return $this
      */
-    public function setFilter(array $filter): DocumentsQuery
+    public function setFilter(array $filter): self
     {
         $this->filter = $filter;
 
@@ -49,8 +80,10 @@ public function setFilter(array $filter): DocumentsQuery
 
     /**
      * @param bool|null $retrieveVectors boolean value to show _vector details
+     *
+     * @return $this
      */
-    public function setRetrieveVectors(?bool $retrieveVectors): DocumentsQuery
+    public function setRetrieveVectors(?bool $retrieveVectors): self
     {
         $this->retrieveVectors = $retrieveVectors;
 
@@ -64,7 +97,27 @@ public function setRetrieveVectors(?bool $retrieveVectors): DocumentsQuery
      */
     public function hasFilter(): bool
     {
-        return isset($this->filter);
+        return null !== $this->filter;
+    }
+
+    /**
+     * @return array{
+     *     offset?: non-negative-int,
+     *     limit?: non-negative-int,
+     *     fields?: non-empty-list<string>|non-empty-string,
+     *     filter?: list<non-empty-string|list<non-empty-string>>,
+     *     retrieveVectors?: 'true'|'false'
+     * }
+     */
+    public function toArray(): array
+    {
+        return array_filter([
+            'offset' => $this->offset,
+            'limit' => $this->limit,
+            'fields' => $this->getFields(),
+            'filter' => $this->filter,
+            'retrieveVectors' => (null !== $this->retrieveVectors ? ($this->retrieveVectors ? 'true' : 'false') : null),
+        ], static function ($item) { return null !== $item; });
     }
 
     /**
@@ -75,27 +128,16 @@ public function hasFilter(): bool
      *
      * @return array|string|null
      */
-    private function fields()
+    private function getFields()
     {
-        if (!isset($this->fields)) {
+        if (null === $this->fields) {
             return null;
         }
 
-        if ($this->hasFilter()) {
+        if (null !== $this->filter) {
             return $this->fields;
-        } else {
-            return implode(',', $this->fields);
         }
-    }
 
-    public function toArray(): array
-    {
-        return array_filter([
-            'offset' => $this->offset ?? null,
-            'limit' => $this->limit ?? null,
-            'filter' => $this->filter ?? null,
-            'fields' => $this->fields(),
-            'retrieveVectors' => (null !== $this->retrieveVectors ? ($this->retrieveVectors ? 'true' : 'false') : null),
-        ], function ($item) { return null !== $item; });
+        return implode(',', $this->fields);
     }
 }

src/Contracts/FacetSearchQuery.php

@@ -6,55 +6,118 @@
 
 class FacetSearchQuery
 {
+    /**
+     * @var non-empty-string|null
+     */
+    private ?string $facetName = null;
+
+    /**
+     * @var non-empty-string|null
+     */
+    private ?string $facetQuery = null;
+
     private ?string $q = null;
-    private ?string $matchingStrategy = null;
+
+    /**
+     * @var list<non-empty-string|list<non-empty-string>>|null
+     */
     private ?array $filter = null;
-    private ?string $facetQuery = null;
-    private ?string $facetName = null;
 
-    public function setQuery(string $q): FacetSearchQuery
+    /**
+     * @var 'last'|'all'|'frequency'|null
+     */
+    private ?string $matchingStrategy = null;
+
+    /**
+     * @var non-empty-list<non-empty-string>|null
+     */
+    private ?array $attributesToSearchOn = null;
+
+    /**
+     * @return $this
+     */
+    public function setFacetName(string $facetName): self
     {
-        $this->q = $q;
+        $this->facetName = $facetName;
 
         return $this;
     }
 
-    public function setMatchingStrategy(string $matchingStrategy): FacetSearchQuery
+    /**
+     * @return $this
+     */
+    public function setFacetQuery(string $facetQuery): self
     {
-        $this->matchingStrategy = $matchingStrategy;
+        $this->facetQuery = $facetQuery;
 
         return $this;
     }
 
-    public function setFilter(array $filter): FacetSearchQuery
+    /**
+     * @return $this
+     */
+    public function setQuery(string $q): self
+    {
+        $this->q = $q;
+
+        return $this;
+    }
+
+    /**
+     * @param list<non-empty-string|list<non-empty-string>> $filter
+     *
+     * @return $this
+     */
+    public function setFilter(array $filter): self
     {
         $this->filter = $filter;
 
         return $this;
     }
 
-    public function setFacetQuery(string $facetQuery): FacetSearchQuery
+    /**
+     * @param 'last'|'all'|'frequency' $matchingStrategy
+     *
+     * @return $this
+     */
+    public function setMatchingStrategy(string $matchingStrategy): self
     {
-        $this->facetQuery = $facetQuery;
+        $this->matchingStrategy = $matchingStrategy;
 
         return $this;
     }
 
-    public function setFacetName(string $facetName): FacetSearchQuery
+    /**
+     * @param non-empty-list<non-empty-string> $attributesToSearchOn
+     *
+     * @return $this
+     */
+    public function setAttributesToSearchOn(array $attributesToSearchOn): self
     {
-        $this->facetName = $facetName;
+        $this->attributesToSearchOn = $attributesToSearchOn;
 
         return $this;
     }
 
+    /**
+     * @return array{
+     *     facetName?: non-empty-string,
+     *     facetQuery?: non-empty-string,
+     *     q?: string,
+     *     filter?: list<non-empty-string|list<non-empty-string>>,
+     *     matchingStrategy?: 'last'|'all'|'frequency'|null,
+     *     attributesToSearchOn?: non-empty-list<non-empty-string>
+     * }
+     */
     public function toArray(): array
     {
         return array_filter([
+            'facetName' => $this->facetName,
+            'facetQuery' => $this->facetQuery,
             'q' => $this->q,
-            'matchingStrategy' => $this->matchingStrategy,
             'filter' => $this->filter,
-            'facetQuery' => $this->facetQuery,
-            'facetName' => $this->facetName,
-        ], function ($item) { return null !== $item; });
+            'matchingStrategy' => $this->matchingStrategy,
+            'attributesToSearchOn' => $this->attributesToSearchOn,
+        ], static function ($item) { return null !== $item; });
     }
 }

src/Contracts/FederationOptions.php

@@ -8,13 +8,21 @@ class FederationOptions
 {
     private ?float $weight = null;
 
-    public function setWeight(float $weight): FederationOptions
+    /**
+     * @return $this
+     */
+    public function setWeight(float $weight): self
     {
         $this->weight = $weight;
 
         return $this;
     }
 
+    /**
+     * @return array{
+     *     weight?: float,
+     * }
+     */
     public function toArray(): array
     {
         return array_filter([

src/Contracts/HybridSearchOptions.php

@@ -13,7 +13,10 @@ class HybridSearchOptions
      */
     private ?string $embedder = null;
 
-    public function setSemanticRatio(float $ratio): HybridSearchOptions
+    /**
+     * @return $this
+     */
+    public function setSemanticRatio(float $ratio): self
     {
         $this->semanticRatio = $ratio;
 
@@ -22,8 +25,10 @@ public function setSemanticRatio(float $ratio): HybridSearchOptions
 
     /**
      * @param non-empty-string $embedder
+     *
+     * @return $this
      */
-    public function setEmbedder(string $embedder): HybridSearchOptions
+    public function setEmbedder(string $embedder): self
     {
         $this->embedder = $embedder;