Subscriber history endpoint

Author: tatevikg1

src/Common/Service/Provider/PaginatedDataProvider.php

@@ -37,7 +37,11 @@ public function getPaginatedList(
             throw new RuntimeException('Repository not found');
         }
 
-        $items = $repository->getFilteredAfterId($pagination->afterId, $pagination->limit, $filter);
+        $items = $repository->getFilteredAfterId(
+            lastId: $pagination->afterId,
+            limit: $pagination->limit,
+            filter: $filter,
+        );
         $total = $repository->count();
 
         $normalizedItems = array_map(

src/Subscription/Controller/SubscriberController.php

@@ -4,12 +4,17 @@
 
 namespace PhpList\RestBundle\Subscription\Controller;
 
+use DateTimeImmutable;
+use Exception;
 use OpenApi\Attributes as OA;
 use PhpList\Core\Domain\Identity\Model\PrivilegeFlag;
+use PhpList\Core\Domain\Subscription\Model\Filter\SubscriberHistoryFilter;
 use PhpList\Core\Domain\Subscription\Model\Subscriber;
+use PhpList\Core\Domain\Subscription\Model\SubscriberHistory;
 use PhpList\Core\Domain\Subscription\Service\Manager\SubscriberManager;
 use PhpList\Core\Security\Authentication;
 use PhpList\RestBundle\Common\Controller\BaseController;
+use PhpList\RestBundle\Common\Service\Provider\PaginatedDataProvider;
 use PhpList\RestBundle\Common\Validator\RequestValidator;
 use PhpList\RestBundle\Subscription\Request\CreateSubscriberRequest;
 use PhpList\RestBundle\Subscription\Request\UpdateSubscriberRequest;
@@ -19,6 +24,8 @@
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+use Symfony\Component\Validator\Exception\ValidatorException;
 
 /**
  * This controller provides REST API access to subscribers.
@@ -31,17 +38,23 @@ class SubscriberController extends BaseController
 {
     private SubscriberManager $subscriberManager;
     private SubscriberNormalizer $subscriberNormalizer;
+    private PaginatedDataProvider $paginatedDataProvider;
+    private NormalizerInterface $serializer;
 
     public function __construct(
         Authentication $authentication,
         RequestValidator $validator,
         SubscriberManager $subscriberManager,
         SubscriberNormalizer $subscriberNormalizer,
+        PaginatedDataProvider $paginatedDataProvider,
+        NormalizerInterface $serializer,
     ) {
         parent::__construct($authentication, $validator);
         $this->authentication = $authentication;
         $this->subscriberManager = $subscriberManager;
         $this->subscriberNormalizer = $subscriberNormalizer;
+        $this->paginatedDataProvider = $paginatedDataProvider;
+        $this->serializer = $serializer;
     }
 
     #[Route('', name: 'create', methods: ['POST'])]
@@ -225,6 +238,127 @@ public function getSubscriber(Request $request, int $subscriberId): JsonResponse
         return $this->json($this->subscriberNormalizer->normalize($subscriber), Response::HTTP_OK);
     }
 
+    #[Route('/{subscriberId}/history', name: 'history', requirements: ['subscriberId' => '\d+'], methods: ['GET'])]
+    #[OA\Get(
+        path: '/api/v2/subscribers/{subscriberId}/history',
+        description: '🚧 **Status: Beta** – This method is under development. Avoid using in production. ',
+        summary: 'Get subscriber event history',
+        tags: ['subscribers'],
+        parameters: [
+            new OA\Parameter(
+                name: 'php-auth-pw',
+                description: 'Session key obtained from login',
+                in: 'header',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'subscriberId',
+                description: 'Subscriber ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+            new OA\Parameter(
+                name: 'after_id',
+                description: 'Page number (pagination)',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'integer', default: 1)
+            ),
+            new OA\Parameter(
+                name: 'limit',
+                description: 'Max items per page',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'integer', default: 25)
+            ),
+            new OA\Parameter(
+                name: 'ip',
+                description: 'Filter by IP address',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'date_from',
+                description: 'Filter by date (format: Y-m-d)',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string', format: 'date')
+            ),
+            new OA\Parameter(
+                name: 'summery',
+                description: 'Filter by summary text',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            )
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Paginated list of subscriber events',
+                content: new OA\JsonContent(
+                    properties: [
+                        new OA\Property(
+                            property: 'items',
+                            type: 'array',
+                            items: new OA\Items(ref: '#/components/schemas/SubscriberHistory')
+                        ),
+                        new OA\Property(property: 'pagination', ref: '#/components/schemas/CursorPagination')
+                    ],
+                    type: 'object'
+                )
+            ),
+            new OA\Response(
+                response: 403,
+                description: 'Unauthorized',
+                content: new OA\JsonContent(ref: '#/components/schemas/UnauthorizedResponse')
+            ),
+            new OA\Response(
+                response: 404,
+                description: 'Not Found',
+                content: new OA\JsonContent(ref: '#/components/schemas/NotFoundErrorResponse')
+            )
+        ]
+    )]
+    public function getSubscriberHistory(
+        Request $request,
+        #[MapEntity(mapping: ['subscriberId' => 'id'])] ?Subscriber $subscriber = null,
+    ): JsonResponse {
+        $this->requireAuthentication($request);
+
+        if (!$subscriber) {
+            throw $this->createNotFoundException('Subscriber not found.');
+        }
+
+        try {
+            $dateFrom = $request->query->get('date_from');
+            $dateFromFormated = $dateFrom ? new DateTimeImmutable($dateFrom) : null;
+        } catch (Exception $e) {
+            throw new ValidatorException('Invalid date format. Use format: Y-m-d');
+        }
+
+        $filter = new SubscriberHistoryFilter(
+            subscriber: $subscriber,
+            ip: $request->query->get('ip'),
+            dateFrom: $dateFromFormated,
+            summery: $request->query->get('summery'),
+        );
+
+        return $this->json(
+            data: $this->paginatedDataProvider->getPaginatedList(
+                request: $request,
+                normalizer: $this->serializer,
+                className: SubscriberHistory::class,
+                filter: $filter
+            ),
+            status: Response::HTTP_OK,
+        );
+    }
+
+
     #[Route('/{subscriberId}', name: 'delete', requirements: ['subscriberId' => '\d+'], methods: ['DELETE'])]
     #[OA\Delete(
         path: '/api/v2/subscribers/{subscriberId}',

src/Subscription/OpenApi/SwaggerSchemasResponse.php

@@ -105,6 +105,23 @@
         new OA\Property(property: 'value', type: 'string', example: 'United States'),
     ],
 )]
+#[OA\Schema(
+    schema: 'SubscriberHistory',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'ip', type: 'string', example: '127.0.0.1'),
+        new OA\Property(
+            property: 'created_at',
+            type: 'string',
+            format: 'date-time',
+            example: '2022-12-01T10:00:00Z'
+        ),
+        new OA\Property(property: 'summery', type: 'string', example: 'Added by admin'),
+        new OA\Property(property: 'detail', type: 'string', example: 'Added with add-email on test'),
+        new OA\Property(property: 'system_info', type: 'string', example: 'HTTP_USER_AGENT = Mozilla/5.0'),
+    ],
+    type: 'object'
+)]
 class SwaggerSchemasResponse
 {
 }

src/Subscription/Serializer/SubscriberHistoryNormalizer.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpList\RestBundle\Subscription\Serializer;
+
+use PhpList\Core\Domain\Subscription\Model\SubscriberHistory;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+class SubscriberHistoryNormalizer implements NormalizerInterface
+{
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
+    public function normalize($object, string $format = null, array $context = []): array
+    {
+        if (!$object instanceof SubscriberHistory) {
+            return [];
+        }
+
+        return [
+            'id' => $object->getId(),
+            'ip' => $object->getIp(),
+            'created_at' => $object->getCreatedAt()->format('Y-m-d\TH:i:sP'),
+            'summery' => $object->getSummary(),
+            'detail' => $object->getDetail(),
+            'system_info' => $object->getSystemInfo(),
+        ];
+    }
+
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
+    public function supportsNormalization($data, string $format = null): bool
+    {
+        return $data instanceof SubscriberHistory;
+    }
+}