Define an API to retrieve information about stop locations

Author: Bertware

src/Trafiklab/Common/Model/Contract/FindStopLocationEntry.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Trafiklab\Common\Model\Contract;
+
+use Trafiklab\Common\Model\Enum\TransportType;
+
+/**
+ * A stop location found by a FindStopLocationRequest.
+ *
+ * @see FindStopLocationRequest
+ * @see FindStopLocationResponse
+ *
+ * @api
+ * @package Trafiklab\Common\Model\Contract
+ */
+interface FindStopLocationEntry
+{
+    /**
+     * Get the id of this stop area.
+     *
+     * @return string The id of this stop area.
+     */
+    public function getId(): string;
+
+    /**
+     * Get the name of this stop area.
+     *
+     * @return string The name of this stop area.
+     */
+    public function getName(): string;
+
+    /**
+     * The longitude of this stop area.
+     *
+     * @return float The longitude of this stop area.
+     */
+    public function getLongitude(): float;
+
+    /**
+     * The latitude of this stop area.
+     *
+     * @return float The latitude of this stop area.
+     */
+    public function getLatitude(): float;
+
+    /**
+     * The sorting weight for this station. This can be determined by the number of vehicles stopping there, the
+     * number of passengers, ...
+     *
+     * @return int The sorting weight for this station.
+     */
+    public function getWeight(): int;
+
+    /**
+     * Check if a certain mode of transport stops at this stop location.
+     *
+     * @param int $transportType The type of transport, one of the constants in TransportType
+     *
+     * @return bool Whether or not the specified type of traffic can stop in this point. In case an API doesn't provide
+     *              this information, it will always return true.
+     *
+     * @see TransportType
+     */
+    public function isStopAreaForTransportType(int $transportType): bool;
+}

src/Trafiklab/Common/Model/Contract/FindStopLocationRequest.php

@@ -0,0 +1,58 @@
+<?php
+
+
+namespace Trafiklab\Common\Model\Contract;
+
+/**
+ * A FindStopLocationRequest is a request to find a certain stop area by (a part of) its name. This way a stop area ID
+ * can obtained. These APIs are called "Platsupplag" on trafiklab.se.
+ *
+ * @see     FindStopLocationResponse
+ * @api
+ * @package Trafiklab\Common\Model\Contract
+ */
+interface FindStopLocationRequest
+{
+    /**
+     * Set the station name to search after. The maximum length might be limited based on the implementation.
+     * If the input is too long, only the first X characters will be used.
+     *
+     * @param string $searchQuery (A part of) the station name to search after.
+     */
+    function setSearchQuery(string $searchQuery): void;
+
+    /**
+     * Get the station name to search after.
+     *
+     * @return string The station name to search after.
+     */
+    function getSearchQuery(): string;
+
+    /**
+     * Set the language which is used in the response.
+     *
+     * @param string $language The language which is used in the response.
+     */
+    function setLanguage(string $language): void;
+
+    /**
+     * Get the language which is used in the response.
+     *
+     * @return string The language which is used in the response.
+     */
+    function getLanguage(): string;
+
+    /**
+     * Set the maximum number of results. The response might contain fewer results, but never more.
+     *
+     * @param int $maximumNumberOfResults The maximum number of results.
+     */
+    function setMaxNumberOfResults(int $maximumNumberOfResults): void;
+
+    /**
+     * Get the maximum number of results. The response might contain fewer results, but never more.
+     *
+     * @return int The maximum number of results.
+     */
+    function getMaxNumberOfResults(): int;
+}

src/Trafiklab/Common/Model/Contract/FindStopLocationResponse.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Trafiklab\Common\Model\Contract;
+
+use Trafiklab\Common\Internal\WebResponseImpl;
+
+/**
+ * Interface FindStopLocationResponse
+ *
+ * @see     FindStopLocationRequest
+ * @api
+ * @package Trafiklab\Common\Model\Contract
+ */
+interface FindStopLocationResponse
+{
+
+
+    /**
+     * Get the original response from the API.
+     *
+     * @return WebResponse
+     */
+    public function getOriginalApiResponse(): WebResponse;
+
+
+    /**
+     * An array containing the stop areas which were found.
+     *
+     * @return FindStopLocationEntry[]
+     */
+    public function getFoundStopAreas(): array;
+}

src/Trafiklab/Common/Model/Contract/PublicTransportApiWrapper.php

@@ -37,6 +37,13 @@ public function setRoutePlanningApiKey(string $apiKey): void;
      */
     public function setTimeTablesApiKey(string $apiKey): void;
 
+    /**
+     * Set the API key used for finding stop locations.
+     *
+     * @param string $apiKey The API key to use.
+     */
+    public function setFindStopLocationApiKey(string $apiKey): void;
+
     /**
      * Get a timetable for a certain stop.
      *
@@ -54,4 +61,14 @@ public function getTimeTable(TimeTableRequest $timeTableRequest): TimeTableRespo
      * @return RoutePlanningResponse The response from the API.
      */
     public function getRoutePlanning(RoutePlanningRequest $routePlanningRequest): RoutePlanningResponse;
+
+
+    /**
+     * Get a route-planning between two points.
+     *
+     * @param FindStopLocationRequest $findStopLocationRequest The request object containing the query parameters.
+     *
+     * @return FindStopLocationResponse The response from the API.
+     */
+    public function findStopLocation(FindStopLocationRequest $findStopLocationRequest): FindStopLocationResponse;
 }

src/Trafiklab/Common/Model/Contract/RoutePlanningResponse.php

@@ -17,7 +17,7 @@ interface RoutePlanningResponse
     /**
      * Get the original response from the API.
      *
-     * @return WebResponseImpl
+     * @return WebResponse
      */
     public function getOriginalApiResponse(): WebResponse;
 

src/Trafiklab/Common/Model/Contract/TimeTableResponse.php

@@ -2,8 +2,6 @@
 
 namespace Trafiklab\Common\Model\Contract;
 
-use Trafiklab\Common\Internal\WebResponseImpl;
-
 /**
  * A timetable response from a transportation API.
  *
@@ -16,7 +14,8 @@ interface TimeTableResponse
     /**
      * Get the original response from the API.
      *
-     * @return WebResponseImpl
+     * @return WebResponse
+     *
      */
     public function getOriginalApiResponse(): WebResponse;