README

You can use this package to communicate with your transmission installation's web/RPC server.

You can set up transmission by going into preferences > remote > enable remote access.

This package was written against Transmission's RPC spec, if you ever need more info on what each call does or what data it returns, that's the best place to start.

Installation

First you'll need to pull in the library

composer require happydemon/transmission

Short intro

Next you'll need to set up the Transmission object.

$transmission = new \HappyDemon\Transmission\Transmission();

By not defining any config, the object will use sensible defaults to connect to transmission.

Let's retrieve the list of torrents we have in Transmission

var_dump($transmission->torrents()->get());

Config

When initialising a Transmission object you can pass an array with several config options;

ssl boolean

Is the transmission web server served over https?

host string

The host/IP the transmission web server is running on (defaults to 127.0.0.1).

port string

What port is the transmission web server running on (defaults to 9091).

url string

What endpoint is the transmission web server running on (defaults to /transmission/rpc).

username string

What username is used to authenticate? (empty by default)

password string

What password is used to authenticate? (empty by default)

Main torrent methods

Retrieving torrents

Retrieves the list of torrents you see in transmission.

$transmission->torrents()->get();

This will always return an array with HappyDemon\Services\Transmission\Torrents\Entity objects. You can check out the class to see what properties are available to it.

You could also use it to retrieve a single or multiple torrents that you have the ID of:

// Get the torrent with id 1
$transmission->torrents()->get(1);


// Get a few torrents
$transmission->torrents()->get([1,6,12]);

Adding torrents

$torrent = $transmission->torrents()->addFromUrl($urlToTorrent);
$torrent = $transmission->torrents()->addFile($filePath);
$torrent = $transmission->torrents()->addFromBase64($fileBlob);

Using any of these methods will let you add new torrents. Each time it will return a HappyDemon\Services\Transmission\Torrents\Entity object. The catch is, only 3 properties will be set though: id, hashString & name.

You can also add some extra options that would overwrite Transmission's own default settings:

$torrent = $transmission->torrents()->addFromUrl($urlToTorrent, ['uploadLimit' => 512]);

Setting defaults

You could also overwrite Transmission's defaults 'globally'

$torrents = $transmission->torrents()->defaults(['uploadLimit' => 512]);

$torrent = $torrents->addFromUrl($urlToTorrent);

Torrent entity methods

These are the methods that are available on a HappyDemon\Services\Transmission\Torrents\Entity object.

Actions

start

$torrent->start();

Starts the specific torrent.

stop

$torrent->stop();

Stops the specific torrent.

verify

$torrent->verify();

Verifies the specific torrent.

reannounce

$torrent->announce();

Reannounces the specific torrent.

remove

$torrent->remove();

Removes the specific torrent.

move

$torrent->move();

Moves the specific torrent to a different location on your file system.

update

Allows you to update some torrent-specific settings.

$torrent->settings($properties);

You could also update a singular torrent-setting like this:

// remove the download limit
$torrent->setDownloadLimited(false);

// set the bandwidth priority
$torrent->setBandwidthPriority(1);

// set the download limit (in K/s)
$torrent->setDownloadLimit(1024*3);

// Mark files as wanted
// Use an empty array for all files, use an array of ids to be more selective [0,2]
// In this case we only want to download the second file
$torrent->setFilesWanted([1]);

// Mark files as unwanted
// Use an empty array for all files, use an array of ids to be more selective [0,2]
// In this case we don't want to download the first file
$torrent->setFilesUnwanted([0]);

// true if session upload limits are honored
$torrent->setHonorsSessionLimits(true);

// Set a new directory for the torrent's contents
$torrent->setLocation('c:/downloads');

// Set the peer limit (max amount of peer)
$torrent->setPeerLimit(40);

// Set the priority for files to high
// Use en empty array to update priority for all files
// or use the file ids [0,2]
$torrent->setPriorityHigh([]);

// Set the priority for files to low
// Use en empty array to update priority for all files
// or use the file ids [0,2]
$torrent->setPriorityLow(false);

// Set the priority for files to normall
// Use en empty array to update priority for all files
// or use the file ids [0,2]
$torrent->setPriorityNormal(false);

// Set the seed ratio limit
$torrent->setSeedRatioLimit(1.2);

// Set the seed ratio mode
// 0 = global, 1 = see seedRatioLimit, 2 = unlimitted
$torrent->setSeedRatioMode(1);

// Change the upload limit (in K/s)
$torrent->setUploadLimit(512);

// Should the torrent's upload be limitted?
$torrent->setUploadLimited(false);

Getters

The entity has a lot of properties, however I've added a few getters for ease-of-use:

status

$torrent->status();

Will return the torrents status as a string, whereas $torrent->status only returns a number.

activityDate

$torrent->activityDate();

Will return a DateTime object, representing the last time torrent activity happened

addedDate

$torrent->addedDate();

Will return a DateTime object, representing the date/time the torrent was added.

doneDate

$torrent->doneDate();

Will return a DateTime object, representing time the torrent was completed.

percentDone

$torrent->percentDone();

Will return the percentage that the torrent is completed whereas $torrent->percentDone would return this as a float.