feat(ZMS-3460): create endpoint for free appointments grouped by office

zmscitizenapi/routing.php

@@ -309,6 +309,48 @@ function createLanguageRoutes($app, $path, $controller, $name, $method = 'get'):
     "get"
 );
 
+/**
+ * @swagger
+ * /available-appointments-by-office/:
+ *   get:
+ *     summary: Get available appointments for a specific day grouped by office
+ *     tags:
+ *       - appointments
+ *     parameters:
+ *       - name: date
+ *         description: Date in format YYYY-MM-DD
+ *         in: query
+ *         required: true
+ *         type: string
+ *       - name: officeId
+ *         description: Comma separated Office IDs
+ *         in: query
+ *         required: true
+ *         type: string
+ *       - name: serviceIds
+ *         description: Comma separated Service IDs
+ *         in: query
+ *         required: true
+ *         type: string
+ *     responses:
+ *       200:
+ *         description: List of available appointments grouped by office id
+ *         schema:
+ *           type: object
+ *           properties:
+ *             meta:
+ *               $ref: "schema/metaresult.json"
+ *             data:
+ *               $ref: "schema/citizenapi/availableAppointments.json"
+ */
+createLanguageRoutes(
+    \App::$slim,
+    '/available-appointments-by-office/',
+    '\BO\Zmscitizenapi\Controllers\Availability\AvailableAppointmentsListController',
+    "AvailableAppointmentsListController",
+    "get"
+);
+
 /**
  * @swagger
  * /appointment/:

zmscitizenapi/src/Zmscitizenapi/Controllers/Availability/AvailableAppointmentsListByOfficeController.php

@@ -0,0 +1,43 @@
+<?php
+declare(strict_types=1);
+
+namespace BO\Zmscitizenapi\Controllers\Availability;
+
+use BO\Zmscitizenapi\BaseController;
+use BO\Zmscitizenapi\Localization\ErrorMessages;
+use BO\Zmscitizenapi\Services\Availability\AvailableAppointmentsListService;
+use BO\Zmscitizenapi\Services\Core\ValidationService;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+class AvailableAppointmentsListByOfficeController extends BaseController
+{
+    private AvailableAppointmentsListService $service;
+
+    public function __construct()
+    {
+        $this->service = new AvailableAppointmentsListService();
+    }
+
+    public function readResponse(RequestInterface $request, ResponseInterface $response, array $args): ResponseInterface
+    {
+        $requestErrors = ValidationService::validateServerGetRequest($request);
+        if (!empty($requestErrors['errors'])) {
+            return $this->createJsonResponse(
+                $response,
+                $requestErrors,
+                ErrorMessages::get('invalidRequest', $this->language)['statusCode']
+            );
+        }
+
+        $result = $this->service->getAvailableAppointmentsListByOffice($request->getQueryParams());
+
+        return is_array($result) && isset($result['errors'])
+            ? $this->createJsonResponse(
+                $response,
+                $result,
+                ErrorMessages::getHighestStatusCode($result['errors'])
+            )
+            : $this->createJsonResponse($response, $result->toArray(), 200);
+    }
+}

zmscitizenapi/src/Zmscitizenapi/Models/ProcessFreeSlotsGroupByOffice.php

@@ -0,0 +1,55 @@
+<?php
+declare(strict_types=1);
+
+namespace BO\Zmscitizenapi\Models;
+
+use BO\Zmsentities\Schema\Entity;
+use InvalidArgumentException;
+use JsonSerializable;
+
+class ProcessFreeSlotsGroupByOffice extends Entity implements JsonSerializable
+{
+
+    public static $schema = 'citizenapi/processFreeSlots.json';
+
+    /** @var array|null */
+    public array|null $appointmentTimestamps = [];
+
+    /**
+     * @param array $appointmentTimestamps
+     */
+    public function __construct(array $appointmentTimestamps = [])
+    {
+
+        $this->appointmentTimestamps = array_map('intval', $appointmentTimestamps);
+
+        $this->ensureValid();
+    }
+
+    private function ensureValid(): void
+    {
+        if (!$this->testValid()) {
+            throw new InvalidArgumentException('The provided data is invalid according to the schema.');
+        }
+    }
+
+    /**
+     * Converts the model data back into an array for serialization.
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        return [
+            'appointmentTimestamps' => $this->appointmentTimestamps,
+        ];
+    }
+
+    /**
+     * Implementation of JsonSerializable.
+     */
+    public function jsonSerialize(): mixed
+    {
+        return $this->toArray();
+    }
+}

zmscitizenapi/src/Zmscitizenapi/Services/Availability/AvailableAppointmentsListService.php

@@ -25,12 +25,14 @@ private function extractClientData(array $queryParams): object
     {
         return (object) [
             'date' => isset($queryParams['date']) ? (string) $queryParams['date'] : null,
-            'officeId' => isset($queryParams['officeId']) ? (int) $queryParams['officeId'] : null,
+            'officeIds' => isset($queryParams['officeId'])
+                ? array_map('trim', explode(',', (string) $queryParams['officeId']))
+                : [],
             'serviceIds' => isset($queryParams['serviceId'])
-                ? array_map('trim', explode(',', $queryParams['serviceId']))
+                ? array_map('trim', explode(',', (string) $queryParams['serviceId']))
                 : [],
             'serviceCounts' => isset($queryParams['serviceCount'])
-                ? array_map('trim', explode(',', $queryParams['serviceCount']))
+                ? array_map('trim', explode(',', (string) $queryParams['serviceCount']))
                 : []
         ];
     }
@@ -39,19 +41,32 @@ private function validateClientData(object $data): array
     {
         return ValidationService::validateGetAvailableAppointments(
             $data->date,
-            $data->officeId,
+            $data->officeIds,
             $data->serviceIds,
             $data->serviceCounts
         );
     }
 
-    private function getAvailableAppointments(object $data): array|AvailableAppointments
+    private function getAvailableAppointments(object $data, ?bool $groupByOffice = false): array|AvailableAppointments
     {
         return ZmsApiFacadeService::getAvailableAppointments(
             $data->date,
-            $data->officeId,
+            $data->officeIds,
             $data->serviceIds,
-            $data->serviceCounts
+            $data->serviceCounts,
+            $groupByOffice
         );
     }
+
+    public function getAvailableAppointmentsListByOffice($queryParams)
+    {
+        $clientData = $this->extractClientData($queryParams);
+
+        $errors = $this->validateClientData($clientData);
+        if (!empty($errors['errors'])) {
+            return $errors;
+        }
+
+        return $this->getAvailableAppointments($clientData, true);
+    }
 }

zmscitizenapi/src/Zmscitizenapi/Services/Availability/AvailableDaysListService.php

@@ -25,16 +25,12 @@ private function extractClientData(array $queryParams): object
     {
         $serviceCount = $queryParams['serviceCount'] ?? '';
         $serviceCounts = !empty($serviceCount)
-            ? array_map('trim', explode(',', $serviceCount))
+            ? array_map('trim', explode(',', (string) $serviceCount))
             : [];
 
         return (object) [
-            'officeId' => isset($queryParams['officeId']) && is_numeric($queryParams['officeId'])
-                ? (int)$queryParams['officeId']
-                : null,
-            'serviceId' => isset($queryParams['serviceId']) && is_numeric($queryParams['serviceId'])
-                ? (int)$queryParams['serviceId']
-                : null,
+            'officeIds' => array_map('trim', explode(',', (string) $queryParams['officeId'] ?? '')),
+            'serviceIds' => array_map('trim', explode(',', (string) $queryParams['serviceId'] ?? '')),
             'serviceCounts' => $serviceCounts,
             'startDate' => $queryParams['startDate'] ?? null,
             'endDate' => $queryParams['endDate'] ?? null
@@ -44,19 +40,19 @@ private function extractClientData(array $queryParams): object
     private function validateClientData(object $data): array
     {
         return ValidationService::validateGetBookableFreeDays(
-            $data->officeId,
-            $data->serviceId,
+            $data->officeIds,
+            $data->serviceIds,
             $data->startDate,
             $data->endDate,
             $data->serviceCounts
         );
     }
 
-    private function getAvailableDays(object $data): array|AvailableDays
+    private function getAvailableDays(object $data): AvailableDays
     {
         return ZmsApiFacadeService::getBookableFreeDays(
-            $data->officeId,
-            $data->serviceId,
+            $data->officeIds,
+            $data->serviceIds,
             $data->serviceCounts,
             $data->startDate,
             $data->endDate

zmscitizenapi/src/Zmscitizenapi/Services/Core/ValidationService.php

@@ -85,19 +85,19 @@ public static function validateServiceLocationCombination(int $officeId, array $
     }
 
     public static function validateGetBookableFreeDays(
-        ?int $officeId, 
-        ?int $serviceId, 
+        ?array $officeIds,
+        ?array $serviceIds,
         ?string $startDate, 
         ?string $endDate, 
         ?array $serviceCounts
     ): array {
         $errors = [];
 
-        if (!self::isValidOfficeId($officeId)) {
+        if (!self::isValidOfficeIds($officeIds)) {
             $errors[] = self::getError('invalidOfficeId');
         }
 
-        if (!self::isValidServiceId($serviceId)) {
+        if (!self::isValidServiceIds($serviceIds)) {
             $errors[] = self::getError('invalidServiceId');
         }
 
@@ -143,7 +143,7 @@ public static function validateGetProcessById(?int $processId, ?string $authKey)
 
     public static function validateGetAvailableAppointments(
         ?string $date, 
-        ?int $officeId, 
+        ?array $officeIds,
         ?array $serviceIds, 
         ?array $serviceCounts
     ): array {
@@ -153,7 +153,7 @@ public static function validateGetAvailableAppointments(
             $errors[] = self::getError('invalidDate');
         }
 
-        if (!self::isValidOfficeId($officeId)) {
+        if (!self::isValidOfficeIds($officeIds)) {
             $errors[] = self::getError('invalidOfficeId');
         }
 
@@ -357,14 +357,9 @@ private static function isValidNumericArray(array $array): bool
         return !empty($array) && array_filter($array, 'is_numeric') === $array;
     }
 
-    private static function isValidOfficeId(?int $officeId): bool
-    {
-        return !empty($officeId) && $officeId > 0;
-    }
-
-    private static function isValidServiceId(?int $serviceId): bool
+    private static function isValidOfficeIds(?array $officeIds): bool
     {
-        return !empty($serviceId) && $serviceId > 0;
+        return !empty($officeIds) && self::isValidNumericArray($officeIds);
     }
 
     private static function isValidScopeId(?int $scopeId): bool
@@ -426,4 +421,14 @@ private static function isValidCustomTextfield(?string $customTextfield): bool
     {
         return $customTextfield === null || (is_string($customTextfield) && strlen(trim($customTextfield)) > 0);
     }
+
+    private static function isValidOfficeId(?int $officeId): bool
+    {
+        return !empty($officeId) && $officeId > 0;
+    }
+
+    private static function isValidServiceId(?int $serviceId): bool
+    {
+        return !empty($serviceId) && $serviceId > 0;
+    }
 }