Merge pull request #10 from MartialGeek/torrent_id_list

New type TorrentIdList

README.md

@@ -12,7 +12,7 @@ with PHPUnit and as close as possible from the original RPC interface.
 With composer:
 
 ```sh
-composer require 'martial/transmission-api:~1.0'
+composer require 'martial/transmission-api:~2.0'
 ```
 
 ## Usage
@@ -34,7 +34,7 @@ You may want to use a logger:
 $logger = new \Monolog\Logger('transmission');
 $logger->pushHandler(new \Monolog\Handler\StreamHandler('php://stdout'));
 
-$api->setLogger($logger);
+$api = new \Martial\Transmission\API\RpcClient($httpClient, 'rpc-username', 'rpc-password', $logger);
 ```
 
 ### Session ID

UPGRADE-2.0.md

@@ -0,0 +1,56 @@
+# UPGRADE FROM 1.x TO 2.0
+
+## Torrent IDs
+
+The array of torrent IDs provided as an argument of almost all the client's methods is replaced by a new class
+\Martial\Transmission\API\TorrentIdList. This class has been created to ensure that the request to the
+Transmission RPC API is well formatted.
+The constructor of this class has one argument, your array of IDs.
+
+Before:
+
+```php
+$api = new \Martial\Transmission\API\RpcClient($guzzle, $rpcUsername, $rpcPassword);
+$sessionId = // Fetch a new session ID
+$torrentIds = [42, 43, 44];
+$api->torrentGet($sessionId, $torrentIds, [
+    \Martial\Transmission\API\Argument\Torrent\Get::ID,
+    \Martial\Transmission\API\Argument\Torrent\Get::NAME,
+    \Martial\Transmission\API\Argument\Torrent\Get::STATUS
+]);
+```
+
+Now:
+
+```php
+$api = new \Martial\Transmission\API\RpcClient($guzzle, $rpcUsername, $rpcPassword);
+$sessionId = // Fetch a new session ID
+$torrentIds = new \Martial\Transmission\API\TorrentIdList([42, 43, 44]);
+$api->torrentGet($sessionId, $torrentIds, [
+    \Martial\Transmission\API\Argument\Torrent\Get::ID,
+    \Martial\Transmission\API\Argument\Torrent\Get::NAME,
+    \Martial\Transmission\API\Argument\Torrent\Get::STATUS
+]);
+```
+
+## Logger
+
+The method \Martial\Transmission\API\TransmissionAPI::setLogger() has been removed because it violated the SRP
+principle. The logger can now be injected as fourth argument of the client's controller.
+
+Before:
+
+```php
+$api = new \Martial\Transmission\API\RpcClient($guzzle, $rpcUsername, $rpcPassword);
+$logger = new \Monolog\Logger('transmission');
+$logger->pushHandler(new \Monolog\Handler\StreamHandler('php://stdout'));
+$api->setLogger($logger);
+```
+
+Now:
+
+```php
+$logger = new \Monolog\Logger('transmission');
+$logger->pushHandler(new \Monolog\Handler\StreamHandler('php://stdout'));
+$api = new \Martial\Transmission\API\RpcClient($guzzle, $rpcUsername, $rpcPassword, $logger);
+```

doc/examples.php

@@ -2,18 +2,26 @@
 
 // Load composer
 
+use GuzzleHttp\Client;
+use Martial\Transmission\API\Argument\Torrent\Add;
+use Martial\Transmission\API\Argument\Torrent\Get;
+use Martial\Transmission\API\CSRFException;
+use Martial\Transmission\API\RpcClient;
+use Martial\Transmission\API\TorrentIdList;
+use Martial\Transmission\API\TransmissionAPI;
+use Monolog\Handler\StreamHandler;
+use Monolog\Logger;
+
 $rpcUri = 'http://42.42.42.42:9091/transmission/rpc';
 $rpcUsername = 'transmission';
 $rpcPassword = 'transmission';
 $newTorrentFile = '/tmp/debian-8.2.0-amd64-CD-1.iso.torrent';
 
-$guzzle = new GuzzleHttp\Client(['base_uri' => $rpcUri]);
-$api = new \Martial\Transmission\API\RpcClient($guzzle, $rpcUsername, $rpcPassword);
-
-$logger = new \Monolog\Logger('transmission');
-$logger->pushHandler(new \Monolog\Handler\StreamHandler('php://stdout'));
+$guzzle = new Client(['base_uri' => $rpcUri]);
+$logger = new Logger('transmission');
+$logger->pushHandler(new StreamHandler('php://stdout'));
 
-$api->setLogger($logger);
+$api = new RpcClient($guzzle, $rpcUsername, $rpcPassword, $logger);
 
 /**
  * @param array $torrentList
@@ -23,27 +31,27 @@ function printTorrentData(array $torrentList)
     foreach ($torrentList as $torrentData) {
         printf(
             'The status of the torrent "%s" with the ID %d is "%s".',
-            $torrentData[\Martial\Transmission\API\Argument\Torrent\Get::NAME],
-            $torrentData[\Martial\Transmission\API\Argument\Torrent\Get::ID],
-            $torrentData[\Martial\Transmission\API\Argument\Torrent\Get::STATUS]
+            $torrentData[Get::NAME],
+            $torrentData[Get::ID],
+            $torrentData[Get::STATUS]
         );
 
         echo PHP_EOL;
     }
 }
 
 /**
- * @param \Martial\Transmission\API\TransmissionAPI $api
+ * @param TransmissionAPI $api
  * @param $sessionId
  * @param array $ids
  * @return array
  */
-function getTorrentData(\Martial\Transmission\API\TransmissionAPI $api, $sessionId, array $ids)
+function getTorrentData(TransmissionAPI $api, $sessionId, array $ids)
 {
-    $torrentList = $api->torrentGet($sessionId, $ids, [
-        \Martial\Transmission\API\Argument\Torrent\Get::ID,
-        \Martial\Transmission\API\Argument\Torrent\Get::NAME,
-        \Martial\Transmission\API\Argument\Torrent\Get::STATUS
+    $torrentList = $api->torrentGet($sessionId, new TorrentIdList($ids), [
+        Get::ID,
+        Get::NAME,
+        Get::STATUS
     ]);
 
 
@@ -66,19 +74,19 @@ function checkNotEmptyList(array $torrentList)
 // Fetching a new session ID
 try {
     $api->sessionGet($sessionId);
-} catch (\Martial\Transmission\API\CSRFException $e) {
+} catch (CSRFException $e) {
     $sessionId = $e->getSessionId();
 }
 
 // Adding a new torrent to the download queue
 $torrentData = $api->torrentAdd($sessionId, [
-    \Martial\Transmission\API\Argument\Torrent\Add::FILENAME => $newTorrentFile
+    Add::FILENAME => $newTorrentFile
 ]);
 
 printf(
     'New torrent "%s" with ID %d added:',
-    $torrentData[\Martial\Transmission\API\Argument\Torrent\Get::NAME],
-    $torrentData[\Martial\Transmission\API\Argument\Torrent\Get::ID]
+    $torrentData[Get::NAME],
+    $torrentData[Get::ID]
 );
 echo PHP_EOL;
 
@@ -88,27 +96,29 @@ function checkNotEmptyList(array $torrentList)
 printTorrentData($torrentList);
 
 // Stopping the first torrent
-$api->torrentStop($sessionId, [$torrentList[0][\Martial\Transmission\API\Argument\Torrent\Get::ID]]);
+$api->torrentStop($sessionId, new TorrentIdList(
+    [$torrentList[0][Get::ID]]
+));
 
-sleep(1);
+sleep(1); // The transmission API is not real time
 
 $torrentList = getTorrentData($api, $sessionId, []);
 checkNotEmptyList($torrentList);
 echo 'Torrent list:' . PHP_EOL;
 printTorrentData($torrentList);
 
 // Starting the first torrent
-$api->torrentStart($sessionId, [$torrentList[0][\Martial\Transmission\API\Argument\Torrent\Get::ID]]);
+$api->torrentStart($sessionId, new TorrentIdList([$torrentList[0][Get::ID]]));
 
-sleep(1); // The transmission API is not real time
+sleep(1);
 
-$torrentList = getTorrentData($api, $sessionId, [$torrentList[0][\Martial\Transmission\API\Argument\Torrent\Get::ID]]);
+$torrentList = getTorrentData($api, $sessionId, [$torrentList[0][Get::ID]]);
 checkNotEmptyList($torrentList);
 echo 'Torrent list:' . PHP_EOL;
 printTorrentData($torrentList);
 
 // Removing the first torrent
-$api->torrentRemove($sessionId, [$torrentList[0][\Martial\Transmission\API\Argument\Torrent\Get::ID]], true);
+$api->torrentRemove($sessionId, new TorrentIdList([$torrentList[0][Get::ID]]), true);
 
 sleep(1);