Typehint Batch results

src/Contracts/Batch.php

@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Meilisearch\Contracts;
+
+use Meilisearch\Contracts\TaskDetails\UnknownTaskDetails;
+use Meilisearch\Exceptions\LogicException;
+
+/**
+ * @phpstan-import-type RawBatchStats from BatchStats
+ * @phpstan-import-type RawBatchProgress from BatchProgress
+ *
+ * @phpstan-type RawBatch array{
+ *     uid: non-negative-int,
+ *     details: array<mixed>,
+ *     stats: RawBatchStats,
+ *     duration: non-empty-string|null,
+ *     startedAt: non-empty-string,
+ *     finishedAt: non-empty-string|null,
+ *     progress: RawBatchProgress|null,
+ *     batchStrategy?: non-empty-string|null
+ * }
+ */
+final class Batch implements \ArrayAccess
+{
+    /**
+     * @param non-negative-int      $uid
+     * @param non-empty-string|null $duration
+     * @param non-empty-string|null $batchStrategy
+     * @param RawBatch              $raw
+     */
+    public function __construct(
+        private readonly int $uid,
+        private readonly TaskDetails $details,
+        private readonly BatchStats $stats,
+        private readonly ?string $duration,
+        private readonly \DateTimeImmutable $startedAt,
+        private readonly ?\DateTimeImmutable $finishedAt,
+        private readonly ?BatchProgress $progress,
+        private readonly ?string $batchStrategy,
+        private readonly array $raw,
+    ) {
+    }
+
+    /**
+     * @return non-negative-int
+     */
+    public function getUid(): int
+    {
+        return $this->uid;
+    }
+
+    public function getDetails(): TaskDetails
+    {
+        return $this->details;
+    }
+
+    public function getStats(): BatchStats
+    {
+        return $this->stats;
+    }
+
+    /**
+     * @return non-empty-string|null
+     */
+    public function getDuration(): ?string
+    {
+        return $this->duration;
+    }
+
+    public function getStartedAt(): \DateTimeImmutable
+    {
+        return $this->startedAt;
+    }
+
+    public function getFinishedAt(): ?\DateTimeImmutable
+    {
+        return $this->finishedAt;
+    }
+
+    /**
+     * Real-time progress while the batch is processing; null when finished.
+     * When present, `percentage` is documented by Meilisearch as 0.0–100.0.
+     */
+    public function getProgress(): ?BatchProgress
+    {
+        return $this->progress;
+    }
+
+    /**
+     * Free-form reason why the batch stopped accepting tasks (not a closed enum).
+     *
+     * @return non-empty-string|null
+     */
+    public function getBatchStrategy(): ?string
+    {
+        return $this->batchStrategy;
+    }
+
+    /**
+     * @return RawBatch
+     */
+    public function toArray(): array
+    {
+        return $this->raw;
+    }
+
+    public function offsetSet(mixed $offset, mixed $value): void
+    {
+        throw new LogicException('The Batch object is immutable.');
+    }
+
+    public function offsetExists(mixed $offset): bool
+    {
+        return \array_key_exists($offset, $this->raw);
+    }
+
+    public function offsetUnset(mixed $offset): void
+    {
+        throw new LogicException('The Batch object is immutable.');
+    }
+
+    public function offsetGet(mixed $offset): mixed
+    {
+        return $this->raw[$offset] ?? null;
+    }
+
+    /**
+     * @param RawBatch $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            $data['uid'],
+            UnknownTaskDetails::fromArray($data['details']),
+            BatchStats::fromArray($data['stats']),
+            $data['duration'] ?? null,
+            new \DateTimeImmutable($data['startedAt']),
+            null !== $data['finishedAt']
+                ? new \DateTimeImmutable($data['finishedAt']) : null,
+            null !== ($data['progress'] ?? null) ? BatchProgress::fromArray($data['progress']) : null,
+            $data['batchStrategy'] ?? null,
+            $data,
+        );
+    }
+}

src/Contracts/BatchEmbedderRequests.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Meilisearch\Contracts;
+
+/**
+ * @phpstan-type RawBatchEmbedderRequests array{
+ *     total: non-negative-int,
+ *     failed: non-negative-int,
+ *     lastError?: non-empty-string|null
+ * }
+ */
+final class BatchEmbedderRequests
+{
+    /**
+     * @param non-negative-int      $total
+     * @param non-negative-int      $failed
+     * @param non-empty-string|null $lastError
+     */
+    public function __construct(
+        private readonly int $total,
+        private readonly int $failed,
+        private readonly ?string $lastError = null,
+    ) {
+    }
+
+    /**
+     * @return non-negative-int
+     */
+    public function getTotal(): int
+    {
+        return $this->total;
+    }
+
+    /**
+     * @return non-negative-int
+     */
+    public function getFailed(): int
+    {
+        return $this->failed;
+    }
+
+    /**
+     * @return non-empty-string|null
+     */
+    public function getLastError(): ?string
+    {
+        return $this->lastError;
+    }
+
+    /**
+     * @param RawBatchEmbedderRequests $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            $data['total'],
+            $data['failed'],
+            $data['lastError'] ?? null,
+        );
+    }
+}

src/Contracts/BatchProgress.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Meilisearch\Contracts;
+
+/**
+ * @phpstan-import-type RawBatchProgressStep from BatchProgressStep
+ *
+ * @phpstan-type RawBatchProgress array{
+ *     steps: list<RawBatchProgressStep>,
+ *     percentage: float
+ * }
+ */
+final class BatchProgress
+{
+    /**
+     * @param list<BatchProgressStep> $steps
+     */
+    public function __construct(
+        private readonly array $steps,
+        private readonly float $percentage,
+    ) {
+    }
+
+    /**
+     * @return list<BatchProgressStep>
+     */
+    public function getSteps(): array
+    {
+        return $this->steps;
+    }
+
+    public function getPercentage(): float
+    {
+        return $this->percentage;
+    }
+
+    /**
+     * @param RawBatchProgress $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            array_map(
+                static fn (array $step) => BatchProgressStep::fromArray($step),
+                $data['steps'],
+            ),
+            $data['percentage'],
+        );
+    }
+}

src/Contracts/BatchProgressStep.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Meilisearch\Contracts;
+
+/**
+ * @phpstan-type RawBatchProgressStep array{
+ *     currentStep: non-empty-string,
+ *     finished: non-negative-int,
+ *     total: non-negative-int
+ * }
+ */
+final class BatchProgressStep
+{
+    /**
+     * @param non-empty-string $currentStep
+     * @param non-negative-int $finished
+     * @param non-negative-int $total
+     */
+    public function __construct(
+        private readonly string $currentStep,
+        private readonly int $finished,
+        private readonly int $total,
+    ) {
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    public function getCurrentStep(): string
+    {
+        return $this->currentStep;
+    }
+
+    /**
+     * @return non-negative-int
+     */
+    public function getFinished(): int
+    {
+        return $this->finished;
+    }
+
+    /**
+     * @return non-negative-int
+     */
+    public function getTotal(): int
+    {
+        return $this->total;
+    }
+
+    /**
+     * @param RawBatchProgressStep $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            $data['currentStep'],
+            $data['finished'],
+            $data['total'],
+        );
+    }
+}