From c323c6064d6450f334f34e8e0e6f1e85ec1157e2 Mon Sep 17 00:00:00 2001
From: "Syed I.R" <syed@lukonet.com>
Date: Sat, 8 Sep 2018 18:38:09 +0530
Subject: [PATCH] Update PHPDocs, Add Return Types and Bump Version.

---
 src/Client.php | 126 +++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 106 insertions(+), 20 deletions(-)

diff --git a/src/Client.php b/src/Client.php
index 649d466..2edab7e 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -31,7 +31,7 @@ class Client
      *
      * @var string
      */
-    const VERSION = '1.3.1';
+    public const VERSION = '1.3.2';
 
     /**
      * Transmission-RPC Hostname
@@ -57,20 +57,20 @@ class Client
     /**
      * @var History
      */
-    private $responseHistory;
+    protected $responseHistory;
 
     /**
      * @var Builder
      */
-    private $httpClientBuilder;
+    protected $httpClientBuilder;
 
     /**
      * Instantiate a new Transmission Client.
      *
-     * @param null|string  $hostname
-     * @param null|int     $port
-     * @param null|string  $username
-     * @param null|string  $password
+     * @param string|null  $hostname
+     * @param int|null     $port
+     * @param string|null  $username
+     * @param string|null  $password
      * @param Builder|null $httpClientBuilder
      */
     public function __construct(
@@ -115,9 +115,7 @@ public static function create(
         string $username = null,
         string $password = null
     ): self {
-        $client = new static($hostname, $port, $username, $password);
-
-        return $client;
+        return new static($hostname, $port, $username, $password);
     }
 
     /**
@@ -138,9 +136,7 @@ public static function createWithHttpClient(
         string $username = null,
         string $password = null
     ): self {
-        $builder = new Builder($httpClient);
-
-        return new static($hostname, $port, $username, $password, $builder);
+        return new static($hostname, $port, $username, $password, new Builder($httpClient));
     }
 
     /**
@@ -192,6 +188,9 @@ public function setSessionId(string $sessionId): self
      * @see start()
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function startAll(): bool
     {
@@ -201,12 +200,15 @@ public function startAll(): bool
     /**
      * Start one or more torrents.
      *
-     * @see https://git.io/transmission-rpc-specs Torrent Action Requests.
+     * @see https://git.io/transmission-rpc-specs Transfer Action Requests.
      *
      * @param mixed $ids One or more torrent ids, sha1 hash strings, or both OR "recently-active", for recently-active
      *                   torrents. All torrents are used if no value is given.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function start($ids = null): bool
     {
@@ -223,6 +225,9 @@ public function start($ids = null): bool
      * @param mixed $ids One or more torrent ids, as described in 3.1 of specs.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function startNow($ids = null): bool
     {
@@ -237,8 +242,11 @@ public function startNow($ids = null): bool
      * @see stop()
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
-    public function stopAll()
+    public function stopAll(): bool
     {
         return $this->stop();
     }
@@ -251,6 +259,9 @@ public function stopAll()
      * @param mixed $ids One or more torrent ids, as described in 3.1 of specs.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function stop($ids = null): bool
     {
@@ -267,6 +278,9 @@ public function stop($ids = null): bool
      * @param mixed $ids One or more torrent ids, as described in 3.1 of specs.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function verify($ids = null): bool
     {
@@ -283,6 +297,9 @@ public function verify($ids = null): bool
      * @param mixed $ids One or more torrent ids, as described in 3.1 of specs.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function reannounce($ids = null): bool
     {
@@ -300,6 +317,9 @@ public function reannounce($ids = null): bool
      * @param array $arguments An associative array of arguments to set.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function set($ids, array $arguments): bool
     {
@@ -315,6 +335,9 @@ public function set($ids, array $arguments): bool
      * @param array|null $fields
      *
      * @return Collection
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function getAll(array $fields = null): Collection
     {
@@ -331,6 +354,9 @@ public function getAll(array $fields = null): Collection
      * @param array $fields An array of return fields, no value will fallback to default fields.
      *
      * @return Collection
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function get($ids = null, array $fields = null): Collection
     {
@@ -356,8 +382,11 @@ public function get($ids = null, array $fields = null): Collection
      * @param array       $optionalArgs Other optional arguments.
      *
      * @return Collection
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
-    public function addFile($file, string $savepath = null, array $optionalArgs = [])
+    public function addFile($file, string $savepath = null, array $optionalArgs = []): Collection
     {
         return $this->add($file, true, $savepath, $optionalArgs);
     }
@@ -370,8 +399,11 @@ public function addFile($file, string $savepath = null, array $optionalArgs = []
      * @param array       $optionalArgs Other optional arguments.
      *
      * @return Collection
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
-    public function addUrl($url, string $savepath = null, array $optionalArgs = [])
+    public function addUrl($url, string $savepath = null, array $optionalArgs = []): Collection
     {
         return $this->add($url, false, $savepath, $optionalArgs);
     }
@@ -387,6 +419,9 @@ public function addUrl($url, string $savepath = null, array $optionalArgs = [])
      * @param  array   $optionalArgs Other optional arguments.
      *
      * @return Collection
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function add(
         string $torrent,
@@ -399,7 +434,7 @@ public function add(
         $arguments[$metainfo ? 'metainfo' : 'filename'] = $metainfo ? base64_encode($torrent) : $torrent;
 
         if ($savepath !== null) {
-            $arguments['download-dir'] = (string)$savepath;
+            $arguments['download-dir'] = $savepath;
         }
 
         $data = $this->api('torrent-add', array_merge($arguments, $optionalArgs));
@@ -426,6 +461,9 @@ public function add(
      * @param bool  $deleteLocalData Also remove local data? (default: false).
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function remove($ids, bool $deleteLocalData = false): bool
     {
@@ -445,6 +483,9 @@ public function remove($ids, bool $deleteLocalData = false): bool
      * @param bool   $move     Move from previous location or search "location" for files (default: true).
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function move($ids, string $location, bool $move = true): bool
     {
@@ -463,6 +504,9 @@ public function move($ids, string $location, bool $move = true): bool
      * @param string $name The file or folder's new name.
      *
      * @return array
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function rename($ids, string $path, string $name): array
     {
@@ -479,6 +523,9 @@ public function rename($ids, string $path, string $name): array
      *                         "version", and "session-id"
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function setSettings(array $arguments): bool
     {
@@ -495,6 +542,9 @@ public function setSettings(array $arguments): bool
      * @param array|null $fields
      *
      * @return array
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function getSettings(array $fields = null): array
     {
@@ -507,6 +557,9 @@ public function getSettings(array $fields = null): array
      * @see https://git.io/transmission-rpc-specs "session-stats" for response arguments.
      *
      * @return array
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function sessionStats(): array
     {
@@ -519,6 +572,9 @@ public function sessionStats(): array
      * @see https://git.io/transmission-rpc-specs "blocklist-update" for response arguments.
      *
      * @return array
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function updateBlocklist(): array
     {
@@ -531,6 +587,9 @@ public function updateBlocklist(): array
      * @see https://git.io/transmission-rpc-specs "port-test" for response arguments.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function portTest(): bool
     {
@@ -543,6 +602,9 @@ public function portTest(): bool
      * @see https://git.io/transmission-rpc-specs "session-close".
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function close(): bool
     {
@@ -560,6 +622,9 @@ public function close(): bool
      *                   torrents. All torrents are used if no value is given.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function queueMoveTop($ids = null): bool
     {
@@ -577,6 +642,9 @@ public function queueMoveTop($ids = null): bool
      *                   torrents. All torrents are used if no value is given.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function queueMoveUp($ids = null): bool
     {
@@ -594,6 +662,9 @@ public function queueMoveUp($ids = null): bool
      *                   torrents. All torrents are used if no value is given.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function queueMoveDown($ids = null): bool
     {
@@ -611,6 +682,9 @@ public function queueMoveDown($ids = null): bool
      *                   torrents. All torrents are used if no value is given.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function queueMoveBottom($ids = null): bool
     {
@@ -627,6 +701,9 @@ public function queueMoveBottom($ids = null): bool
      * @param null|string $path Path to check free space (default: download-dir).
      *
      * @return array
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function freeSpace(string $path = null): array
     {
@@ -640,7 +717,10 @@ public function freeSpace(string $path = null): array
     /**
      * Seed Ratio Limit.
      *
-     * @return mixed
+     * @return int|float
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function seedRatioLimit()
     {
@@ -659,6 +739,9 @@ public function seedRatioLimit()
      * @param string $downloadDir Path to download torrents.
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function updateDownloadDir(string $downloadDir): bool
     {
@@ -676,6 +759,9 @@ public function updateDownloadDir(string $downloadDir): bool
      * @param bool   $enableIncompleteDir Is incomplete dir enabled? (default: true).
      *
      * @return bool
+     * @throws NetworkException
+     * @throws TransmissionException
+     * @throws \Http\Client\Exception
      */
     public function updateIncompleteDir(string $incompleteDir, bool $enableIncompleteDir = true): bool
     {
@@ -778,7 +864,7 @@ public function getHttpClient(): HttpMethodsClient
     /**
      * @return History
      */
-    public function getResponseHistory()
+    public function getResponseHistory(): History
     {
         return $this->responseHistory;
     }