Use version 1.0.x as SDK base, better tests and documentation

README.md

@@ -11,10 +11,6 @@ More information can be found at [Trafiklab - ResRobot routeplanner](https://www
 This repository contains a PHP SDK to easily use the ResRobot APIs. This way you don't need to worry about making requests, caching, 
 or parsing responses. All responses are parsed and returned as PHP classes.
 
-**_Work in progress_**: _There is no stable release available yet. If you want to get a sneak peak, 
-you can get it by trying out a 0.x version. However, keep in mind that breaking changes are still possible. 
-A first release is estimated to arrive in one of the next months._
-
 ## Installation
 Installing can be done by using Composer:
 
@@ -49,15 +45,16 @@ you need to obtain an API key from [Trafiklab](https://trafiklab.se) first.
 The following code example illustrates how you can retrieve a timetable for a certain stop.
 
 ```
-  $wrapper = new ResRobotWrapper();
-  
-  $wrapper = $wrapper->createTimeTableRequestObject();
-  $wrapper->setStopId("740000001");
-  $wrapper->setTimeTableType(TimeTableType::DEPARTURES);
-
-  $wrapper->setUserAgent("<YOUR_USER_AGENT>");
-  $wrapper->setTimeTablesApiKey("<YOUR_API_KEY>");
-  $response = $resRobotWrapper->getTimeTable($departuresRequest);
+$wrapper = new ResRobotWrapper();
+
+// Create a new routeplanning object. The wrapper will instantiate an object of the interface type.
+$wrapper = $wrapper->createTimeTableRequestObject();
+$wrapper->setStopId("740000001");
+$wrapper->setTimeTableType(TimeTableType::DEPARTURES);
+
+$wrapper->setUserAgent("<YOUR_USER_AGENT>");
+$wrapper->setTimeTablesApiKey("<YOUR_API_KEY>");
+$response = $resRobotWrapper->getTimeTable($departuresRequest);
 ```
 `<YOUR_API_KEY>` is obtained from [Trafiklab](https://trafiklab.se). `<YOUR_USER_AGENT>` is a string which identifies your application. 
 While this is not enforced in any way, it is good practice to use a clear user agent. 
@@ -74,36 +71,75 @@ This method returns an array of TimeTableEntry instances, each of which describe
 You can look at the code and PHPDoc in order to get up-to-date information on which fields are available. 
 Detailed information about ResRobot responses can be found at the [ResRobot departures/arrivals API page](https://www.trafiklab.se/api/resrobot-reseplanerare).
 
-_Work in progress_
+The following code gives a quick idea on how the SDK is used.
 ```
-   $response->getTimetable()
+$entry = $response->getTimetable()[0]; // Get the first result
+// Type of transport, one of the constants in Trafiklab\Common\Model\Enum\TransportType
+$entry->getTransportType(); 
+// The name of the stop location
+$stop = $timeTableEntry->getStopName()
+// The number of the line
+$lineNumber = $timeTableEntry->getLineNumber();
+// The direction of the vehicle
+$direction = $timeTableEntry->getDirection();
+// The scheduled departure time at the stop
+$scheduledStopTime = $timeTableEntry->getScheduledStopTime();   
 ```
 
 #### Routeplanning
 ##### Request
 The following code example illustrates how you can plan a route from A to B
 
 ```    
-  $queryTime = new DateTime();
-  $queryTime->setTime(18, 0);
-
-  $wrapper = new ResRobotWrapper();
-  
-  $wrapper = $wrapper->createRoutePlanningRequestObject();
-  $wrapper->setOriginId("740000001");
-  $wrapper->setDestinationId("740000002");
-  $wrapper->setDateTime($queryTime);
-
-  $wrapper->setUserAgent(("<YOUR_USER_AGENT>");
-  $wrapper->setRoutePlanningApiKey("<YOUR_API_KEY>");
-  $response = $resRobotWrapper->getRoutePlanning($routePlanningRequest);
+$queryTime = new DateTime();
+$queryTime->setTime(18, 0);
+
+$wrapper = new ResRobotWrapper();
+
+// Create a new routeplanning object. The wrapper will instantiate an object of the interface type.
+$wrapper = $wrapper->createRoutePlanningRequestObject();
+$wrapper->setOriginId("740000001");
+$wrapper->setDestinationId("740000002");
+$wrapper->setDateTime($queryTime);
+
+$wrapper->setUserAgent(("<YOUR_USER_AGENT>");
+$wrapper->setRoutePlanningApiKey("<YOUR_API_KEY>");
+$response = $resRobotWrapper->getRoutePlanning($routePlanningRequest);
 ```
 ##### Response
 
-_Work in progress_
+In order to use the data returned by your request, you can simply call getTrips() on the response object. 
+This method returns an array of Trip instances, each of which describes one departure or arrival. 
+You can look at the code and PHPDoc in order to get up-to-date information on which fields are available. 
+Detailed information about ResRobot responses can be found at the [ResRobot departures/arrivals API page](https://www.trafiklab.se/api/resrobot-reseplanerare).
+
+The following code gives a quick idea on how the SDK is used.
 
 ```
-   $response->getTrips()
+$trip = $response->getTrips()[0]; // Get the first result
+
+// Tell the user about every leg in their journey.
+foreach ($trip->getLegs() as $leg) {
+
+   // There are two types of legs (at this moment): Vehicle journeys, where a vehicle is used, or walking parts
+   // where a user walks between two stations. Not all fields are available for walking parts, so we need to handle them differently.
+
+   if ($leg->getType() == RoutePlanningLegType::VEHICLE_JOURNEY) {
+       $leg->getVehicle()->getType();
+       $leg->getVehicle()->getNumber();
+       $leg->getDirection();
+       $leg->getDeparture()->getStopName();
+       $leg->getDeparture()->getScheduledDepartureTime()->format("H:i");
+       $leg->getDeparture()->getScheduledDepartureTime()->getTimestamp();
+       $leg->getArrival()->getScheduledArrivalTime()->getTimestamp(); 
+       $leg->getArrival()->getStopName();
+       // More fields are available
+   } else if ($leg->getType() == RoutePlanningLegType::WALKING) {
+       // Limited fields when walking!
+       $leg->getDeparture()->getStopName(); // origin
+       $leg->getArrival()->getStopName(); // destination
+   }
+}
 ```
 
 ## Contributing

composer.json

@@ -21,7 +21,7 @@
   "require": {
     "php": ">=7.1",
     "ext-json": "*",
-    "trafiklab/php-sdk-commons": "0.4.0"
+    "trafiklab/php-sdk-commons": "1.0.*"
   },
   "require-dev": {
     "phpunit/phpunit": "^5.5",

src/Trafiklab/ResRobot/Internal/ResRobotClient.php

@@ -20,12 +20,12 @@
 use Trafiklab\Common\Model\Exceptions\ServiceUnavailableException;
 use Trafiklab\ResRobot\Model\ResRobotRoutePlanningRequest;
 use Trafiklab\ResRobot\Model\ResRobotRoutePlanningResponse;
-use Trafiklab\ResRobot\Model\ResRobotTimeTableRequest;
 use Trafiklab\ResRobot\Model\ResRobotStopLocationLookupResponse;
+use Trafiklab\ResRobot\Model\ResRobotTimeTableRequest;
 use Trafiklab\ResRobot\Model\ResRobotTimeTableResponse;
 
 /**
- * @internal Builds requests and gets data
+ * @internal Builds requests and gets data.
  * @package  Trafiklab\ResRobot\Internal
  */
 class ResRobotClient
@@ -58,8 +58,8 @@ public function __construct(WebClient $webClient = null)
 
 
     /**
-     * @param string                   $key
-     * @param ResRobotTimeTableRequest $request
+     * @param string                   $key     The API key to use.
+     * @param ResRobotTimeTableRequest $request The request object holding all parameters.
      *
      * @return TimeTableResponse
      * @throws InvalidKeyException
@@ -101,16 +101,10 @@ public function getTimeTable(string $key, ResRobotTimeTableRequest $request): Ti
     }
 
     /**
-     * @param string $applicationUserAgent
-     */
-    public function setApplicationUserAgent(string $applicationUserAgent): void
-    {
-        $this->applicationUserAgent = $applicationUserAgent;
-    }
-
-    /**
-     * @param string                       $key
-     * @param ResRobotRoutePlanningRequest $request
+     * Get a route planning from A to B.
+     *
+     * @param string                       $key     The API key to use.
+     * @param ResRobotRoutePlanningRequest $request The request object holding all parameters.
      *
      * @return ResRobotRoutePlanningResponse
      * @throws InvalidKeyException
@@ -159,7 +153,7 @@ public function getRoutePlanning(string $key, ResRobotRoutePlanningRequest $requ
     }
 
     /**
-     * @param string                  $key
+     * @param string                    $key
      * @param StopLocationLookupRequest $request
      *
      * @return StopLocationLookupResponse
@@ -187,6 +181,15 @@ public function lookupStopLocation(string $key, StopLocationLookupRequest $reque
         return new ResRobotStopLocationLookupResponse($response, $json);
     }
 
+    /**
+     * Set the user agent of the application using the SDK.
+     *
+     * @param string $applicationUserAgent
+     */
+    public function setApplicationUserAgent(string $applicationUserAgent): void
+    {
+        $this->applicationUserAgent = $applicationUserAgent;
+    }
 
     private function getUserAgent()
     {

src/Trafiklab/ResRobot/Model/ResRobotLeg.php

@@ -41,7 +41,7 @@ public function __construct(array $json)
      *
      * @return VehicleStop The stoplocation at which this leg starts.
      */
-    public function getOrigin(): VehicleStop
+    public function getDeparture(): VehicleStop
     {
         return $this->_origin;
     }
@@ -51,7 +51,7 @@ public function getOrigin(): VehicleStop
      *
      * @return VehicleStop The stoplocation at which this leg ends.
      */
-    public function getDestination(): VehicleStop
+    public function getArrival(): VehicleStop
     {
         return $this->_destination;
     }
@@ -81,13 +81,23 @@ public function getVehicle(): ?Vehicle
     /**
      * Intermediary stops made by the vehicle on this leg.
      *
-     * @return ResRobotStop[] Stops between the origin and destination, excluding the origin and destination.
+     * @return VehicleStop[] Stops between the origin and destination, excluding the origin and destination.
      */
     public function getIntermediaryStops(): array
     {
         return $this->_intermediaryStops;
     }
 
+    public function getDuration(): int
+    {
+        if ($this->getArrival()->getScheduledArrivalTime() == null
+            || $this->getDeparture()->getScheduledDepartureTime() == null) {
+            return 0;
+        }
+        return $this->getArrival()->getScheduledArrivalTime()->getTimestamp() -
+            $this->getDeparture()->getScheduledDepartureTime()->getTimestamp();
+    }
+
     /**
      * The direction of the vehicle on this leg. Can be null in case
      * of a walk between two stop locations.
@@ -109,6 +119,11 @@ public function getType(): string
         return $this->_type;
     }
 
+    /**
+     * Parse (a part of) an API response and store the result in this object.
+     *
+     * @param array $json
+     */
     private function parseApiResponse(array $json)
     {
         $this->_notes = [];

src/Trafiklab/ResRobot/Model/ResRobotRoutePlanningResponse.php

@@ -45,6 +45,8 @@ public function getOriginalApiResponse(): WebResponse
     }
 
     /**
+     * Parse (a part of) an API response and store the result in this object.
+     *
      * @param array $json The API output to parse.
      */
     private function parseApiResponse(array $json): void

src/Trafiklab/ResRobot/Model/ResRobotStop.php

@@ -98,6 +98,11 @@ public function getLongitude(): float
         return $this->_longitude;
     }
 
+    /**
+     * Parse an API response and store the result in this object.
+     *
+     * @param array $json
+     */
     private function parseApiResponse(array $json)
     {
         $this->_stopId = $json['extId'];

src/Trafiklab/ResRobot/Model/ResRobotStopLocationLookupEntry.php

@@ -120,6 +120,11 @@ public function isStopLocationForTransportType(string $transportType): bool
         }
     }
 
+    /**
+     * Parse an API response and store the result in this object.
+     *
+     * @param array $json
+     */
     private function parseApiResponse(array $json)
     {
         $this->_id = $json['extId'];

src/Trafiklab/ResRobot/Model/ResRobotStopLocationLookupResponse.php

@@ -43,6 +43,11 @@ public function getFoundStopLocations(): array
         return $this->_stopLocations;
     }
 
+    /**
+     * Parse (a part of) an API response and store the result in this object.
+     *
+     * @param array $json
+     */
     private function parseApiResponse(array $json)
     {
         $this->_stopLocations = [];

src/Trafiklab/ResRobot/Model/ResRobotTimeTableEntry.php

@@ -144,6 +144,11 @@ public function getTransportType(): string
         return $this->_transportType;
     }
 
+    /**
+     * Parse (a part of) an API response and store the result in this object.
+     *
+     * @param array $json
+     */
     private function parseApiResponse(array $json): void
     {
         $this->_stopId = $json['stopExtId'];

src/Trafiklab/ResRobot/Model/ResRobotTimeTableResponse.php

@@ -57,6 +57,7 @@ public function getOriginalApiResponse(): WebResponse
     }
 
     /**
+     * Parse (a part of) an API response and store the result in this object.
      * @param array $json The API output to parse.
      */
     private function parseApiResponse(array $json): void

src/Trafiklab/ResRobot/Model/ResRobotTrip.php

@@ -5,6 +5,7 @@
 
 use Trafiklab\Common\Model\Contract\RoutePlanningLeg;
 use Trafiklab\Common\Model\Contract\Trip;
+use Trafiklab\Common\Model\Contract\VehicleStop;
 
 /**
  * A Trip, often also called Journey, describes one possibility for travelling between two locations. A Trip can
@@ -41,6 +42,48 @@ public function getLegs(): array
         return $this->_legs;
     }
 
+    /**
+     * Get the duration of this trip in seconds.
+     *
+     * @return int
+     */
+    public function getDuration(): int
+    {
+        return $this->getArrival()->getScheduledArrivalTime()->getTimestamp() -
+            $this->getDeparture()->getScheduledDepartureTime()->getTimestamp();
+    }
+
+    /**
+     * Get the departure for the first leg.
+     *
+     * @return VehicleStop
+     */
+    public function getDeparture(): VehicleStop
+    {
+        if (count($this->_legs) < 1) {
+            return null;
+        }
+        return $this->_legs[0]->getDeparture();
+    }
+
+    /**
+     * Get the arrival for the last leg.
+     *
+     * @return VehicleStop
+     */
+    public function getArrival(): VehicleStop
+    {
+        if (count($this->_legs) < 1) {
+            return null;
+        }
+        return end($this->_legs)->getArrival();
+    }
+
+    /**
+     * Parse (a part of) an API response and store the result in this object.
+     *
+     * @param array $json
+     */
     private function parseApiResponse(array $json)
     {
         $this->_legs = [];

src/Trafiklab/ResRobot/Model/ResRobotVehicle.php

@@ -97,6 +97,10 @@ public function getLineNumber(): string
         return $this->_number;
     }
 
+    /**
+     * Parse (a part of) an API response and store the result in this object.
+     * @param array $json
+     */
     private function parseApiResponse(array $json)
     {
         $this->_name = $json['name'];