Added Created endpoint to serve visits by tag

docs/swagger/paths/v2_tags_{tag}_visits.json

@@ -0,0 +1,154 @@
+{
+    "get": {
+        "operationId": "getTagVisits",
+        "tags": [
+            "Visits"
+        ],
+        "summary": "List visits for tag",
+        "description": "Get the list of visits on any short URL which is tagged with provided tag.",
+        "parameters": [
+            {
+                "$ref": "../parameters/version.json"
+            },
+            {
+                "name": "tag",
+                "in": "path",
+                "description": "The tag from which we want to get the visits.",
+                "required": true,
+                "schema": {
+                    "type": "string"
+                }
+            },
+            {
+                "name": "startDate",
+                "in": "query",
+                "description": "The date (in ISO-8601 format) from which we want to get visits.",
+                "required": false,
+                "schema": {
+                    "type": "string"
+                }
+            },
+            {
+                "name": "endDate",
+                "in": "query",
+                "description": "The date (in ISO-8601 format) until which we want to get visits.",
+                "required": false,
+                "schema": {
+                    "type": "string"
+                }
+            },
+            {
+                "name": "page",
+                "in": "query",
+                "description": "The page to display. Defaults to 1",
+                "required": false,
+                "schema": {
+                    "type": "number"
+                }
+            },
+            {
+                "name": "itemsPerPage",
+                "in": "query",
+                "description": "The amount of items to return on every page. Defaults to all the items",
+                "required": false,
+                "schema": {
+                    "type": "number"
+                }
+            }
+        ],
+        "security": [
+            {
+                "ApiKey": []
+            }
+        ],
+        "responses": {
+            "200": {
+                "description": "List of visits.",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "visits": {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "../definitions/Visit.json"
+                                            }
+                                        },
+                                        "pagination": {
+                                            "$ref": "../definitions/Pagination.json"
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+                "examples": {
+                    "application/json": {
+                        "visits": {
+                            "data": [
+                                {
+                                    "referer": "https://twitter.com",
+                                    "date": "2015-08-20T05:05:03+04:00",
+                                    "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
+                                    "visitLocation": null
+                                },
+                                {
+                                    "referer": "https://t.co",
+                                    "date": "2015-08-20T05:05:03+04:00",
+                                    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
+                                    "visitLocation": {
+                                        "cityName": "Cupertino",
+                                        "countryCode": "US",
+                                        "countryName": "United States",
+                                        "latitude": 37.3042,
+                                        "longitude": -122.0946,
+                                        "regionName": "California",
+                                        "timezone": "America/Los_Angeles"
+                                    }
+                                },
+                                {
+                                    "referer": null,
+                                    "date": "2015-08-20T05:05:03+04:00",
+                                    "userAgent": "some_web_crawler/1.4",
+                                    "visitLocation": null
+                                }
+                            ],
+                            "pagination": {
+                                "currentPage": 5,
+                                "pagesCount": 12,
+                                "itemsPerPage": 10,
+                                "itemsInCurrentPage": 10,
+                                "totalItems": 115
+                            }
+                        }
+                    }
+                }
+            },
+            "404": {
+                "description": "The tag does not exist.",
+                "content": {
+                    "application/problem+json": {
+                        "schema": {
+                            "$ref": "../definitions/Error.json"
+                        }
+                    }
+                }
+            },
+            "500": {
+                "description": "Unexpected error.",
+                "content": {
+                    "application/problem+json": {
+                        "schema": {
+                            "$ref": "../definitions/Error.json"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

docs/swagger/swagger.json

@@ -84,6 +84,9 @@
         "/rest/v{version}/short-urls/{shortCode}/visits": {
             "$ref": "paths/v1_short-urls_{shortCode}_visits.json"
         },
+        "/rest/v{version}/tags/{tag}/visits": {
+            "$ref": "paths/v2_tags_{tag}_visits.json"
+        },
 
         "/rest/v{version}/mercure-info": {
             "$ref": "paths/v2_mercure-info.json"

module/Core/src/Paginator/Adapter/VisitsForTagPaginatorAdapter.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shlinkio\Shlink\Core\Paginator\Adapter;
+
+use Laminas\Paginator\Adapter\AdapterInterface;
+use Shlinkio\Shlink\Core\Model\VisitsParams;
+use Shlinkio\Shlink\Core\Repository\VisitRepositoryInterface;
+
+class VisitsForTagPaginatorAdapter implements AdapterInterface
+{
+    private VisitRepositoryInterface $visitRepository;
+    private string $tag;
+    private VisitsParams $params;
+
+    private ?int $count = null;
+
+    public function __construct(VisitRepositoryInterface $visitRepository, string $tag, VisitsParams $params)
+    {
+        $this->visitRepository = $visitRepository;
+        $this->params = $params;
+        $this->tag = $tag;
+    }
+
+    public function getItems($offset, $itemCountPerPage): array // phpcs:ignore
+    {
+        return $this->visitRepository->findVisitsByTag(
+            $this->tag,
+            $this->params->getDateRange(),
+            $itemCountPerPage,
+            $offset,
+        );
+    }
+
+    public function count(): int
+    {
+        // Since a new adapter instance is created every time visits are fetched, it is reasonably safe to internally
+        // cache the count value.
+        // The reason it is cached is because the Paginator is actually calling the method twice.
+        // An inconsistent value could be returned if between the first call and the second one, a new visit is created.
+        // However, it's almost instant, and then the adapter instance is discarded immediately after.
+
+        if ($this->count !== null) {
+            return $this->count;
+        }
+
+        return $this->count = $this->visitRepository->countVisitsByTag($this->tag, $this->params->getDateRange());
+    }
+}

module/Core/src/Service/VisitsTracker.php

@@ -8,15 +8,19 @@ use Doctrine\ORM;
 use Laminas\Paginator\Paginator;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Shlinkio\Shlink\Core\Entity\ShortUrl;
+use Shlinkio\Shlink\Core\Entity\Tag;
 use Shlinkio\Shlink\Core\Entity\Visit;
 use Shlinkio\Shlink\Core\EventDispatcher\ShortUrlVisited;
 use Shlinkio\Shlink\Core\Exception\ShortUrlNotFoundException;
+use Shlinkio\Shlink\Core\Exception\TagNotFoundException;
 use Shlinkio\Shlink\Core\Model\ShortUrlIdentifier;
 use Shlinkio\Shlink\Core\Model\Visitor;
 use Shlinkio\Shlink\Core\Model\VisitsParams;
+use Shlinkio\Shlink\Core\Paginator\Adapter\VisitsForTagPaginatorAdapter;
 use Shlinkio\Shlink\Core\Paginator\Adapter\VisitsPaginatorAdapter;
 use Shlinkio\Shlink\Core\Repository\ShortUrlRepositoryInterface;
-use Shlinkio\Shlink\Core\Repository\VisitRepository;
+use Shlinkio\Shlink\Core\Repository\TagRepository;
+use Shlinkio\Shlink\Core\Repository\VisitRepositoryInterface;
 
 class VisitsTracker implements VisitsTrackerInterface
 {
@@ -34,9 +38,6 @@ class VisitsTracker implements VisitsTrackerInterface
         $this->anonymizeRemoteAddr = $anonymizeRemoteAddr;
     }
 
-    /**
-     * Tracks a new visit to provided short code from provided visitor
-     */
     public function track(ShortUrl $shortUrl, Visitor $visitor): void
     {
         $visit = new Visit($shortUrl, $visitor, $this->anonymizeRemoteAddr);
@@ -48,8 +49,6 @@ class VisitsTracker implements VisitsTrackerInterface
     }
 
     /**
-     * Returns the visits on certain short code
-     *
      * @return Visit[]|Paginator
      * @throws ShortUrlNotFoundException
      */
@@ -61,7 +60,7 @@ class VisitsTracker implements VisitsTrackerInterface
             throw ShortUrlNotFoundException::fromNotFound($identifier);
         }
 
-        /** @var VisitRepository $repo */
+        /** @var VisitRepositoryInterface $repo */
         $repo = $this->em->getRepository(Visit::class);
         $paginator = new Paginator(new VisitsPaginatorAdapter($repo, $identifier, $params));
         $paginator->setItemCountPerPage($params->getItemsPerPage())
@@ -69,4 +68,26 @@ class VisitsTracker implements VisitsTrackerInterface
 
         return $paginator;
     }
+
+    /**
+     * @return Visit[]|Paginator
+     * @throws TagNotFoundException
+     */
+    public function visitsForTag(string $tag, VisitsParams $params): Paginator
+    {
+        /** @var TagRepository $tagRepo */
+        $tagRepo = $this->em->getRepository(Tag::class);
+        $count = $tagRepo->count(['name' => $tag]);
+        if ($count === 0) {
+            throw TagNotFoundException::fromTag($tag);
+        }
+
+        /** @var VisitRepositoryInterface $repo */
+        $repo = $this->em->getRepository(Visit::class);
+        $paginator = new Paginator(new VisitsForTagPaginatorAdapter($repo, $tag, $params));
+        $paginator->setItemCountPerPage($params->getItemsPerPage())
+                  ->setCurrentPageNumber($params->getPage());
+
+        return $paginator;
+    }
 }

module/Core/src/Service/VisitsTrackerInterface.php

@@ -8,22 +8,24 @@ use Laminas\Paginator\Paginator;
 use Shlinkio\Shlink\Core\Entity\ShortUrl;
 use Shlinkio\Shlink\Core\Entity\Visit;
 use Shlinkio\Shlink\Core\Exception\ShortUrlNotFoundException;
+use Shlinkio\Shlink\Core\Exception\TagNotFoundException;
 use Shlinkio\Shlink\Core\Model\ShortUrlIdentifier;
 use Shlinkio\Shlink\Core\Model\Visitor;
 use Shlinkio\Shlink\Core\Model\VisitsParams;
 
 interface VisitsTrackerInterface
 {
-    /**
-     * Tracks a new visit to provided short code from provided visitor
-     */
     public function track(ShortUrl $shortUrl, Visitor $visitor): void;
 
     /**
-     * Returns the visits on certain short code
-     *
      * @return Visit[]|Paginator
      * @throws ShortUrlNotFoundException
      */
     public function info(ShortUrlIdentifier $identifier, VisitsParams $params): Paginator;
+
+    /**
+     * @return Visit[]|Paginator
+     * @throws TagNotFoundException
+     */
+    public function visitsForTag(string $tag, VisitsParams $params): Paginator;
 }

module/Rest/config/dependencies.config.php

@@ -30,6 +30,7 @@ return [
             Action\ShortUrl\ListShortUrlsAction::class => ConfigAbstractFactory::class,
             Action\ShortUrl\EditShortUrlTagsAction::class => ConfigAbstractFactory::class,
             Action\Visit\ShortUrlVisitsAction::class => ConfigAbstractFactory::class,
+            Action\Visit\TagVisitsAction::class => ConfigAbstractFactory::class,
             Action\Visit\GlobalVisitsAction::class => ConfigAbstractFactory::class,
             Action\Tag\ListTagsAction::class => ConfigAbstractFactory::class,
             Action\Tag\DeleteTagsAction::class => ConfigAbstractFactory::class,
@@ -63,6 +64,7 @@ return [
             'config.url_shortener.domain',
         ],
         Action\Visit\ShortUrlVisitsAction::class => [Service\VisitsTracker::class],
+        Action\Visit\TagVisitsAction::class => [Service\VisitsTracker::class],
         Action\Visit\GlobalVisitsAction::class => [Visit\VisitsStatsHelper::class],
         Action\ShortUrl\ListShortUrlsAction::class => [Service\ShortUrlService::class, 'config.url_shortener.domain'],
         Action\ShortUrl\EditShortUrlTagsAction::class => [Service\ShortUrlService::class],

module/Rest/config/routes.config.php

@@ -27,6 +27,7 @@ return [
 
         // Visits
         Action\Visit\ShortUrlVisitsAction::getRouteDef([$dropDomainMiddleware]),
+        Action\Visit\TagVisitsAction::getRouteDef(),
         Action\Visit\GlobalVisitsAction::getRouteDef(),
 
         // Tags

module/Rest/src/Action/Visit/TagVisitsAction.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shlinkio\Shlink\Rest\Action\Visit;
+
+use Laminas\Diactoros\Response\JsonResponse;
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+use Shlinkio\Shlink\Common\Paginator\Util\PaginatorUtilsTrait;
+use Shlinkio\Shlink\Core\Model\VisitsParams;
+use Shlinkio\Shlink\Core\Service\VisitsTrackerInterface;
+use Shlinkio\Shlink\Rest\Action\AbstractRestAction;
+
+class TagVisitsAction extends AbstractRestAction
+{
+    use PaginatorUtilsTrait;
+
+    protected const ROUTE_PATH = '/tags/{tag}/visits';
+    protected const ROUTE_ALLOWED_METHODS = [self::METHOD_GET];
+
+    private VisitsTrackerInterface $visitsTracker;
+
+    public function __construct(VisitsTrackerInterface $visitsTracker)
+    {
+        $this->visitsTracker = $visitsTracker;
+    }
+
+    public function handle(Request $request): Response
+    {
+        $tag = $request->getAttribute('tag', '');
+        $visits = $this->visitsTracker->visitsForTag($tag, VisitsParams::fromRawData($request->getQueryParams()));
+
+        return new JsonResponse([
+            'visits' => $this->serializePaginator($visits),
+        ]);
+    }
+}