diff --git a/LICENCE b/LICENCE new file mode 100644 index 0000000..4e6e8c8 --- /dev/null +++ b/LICENCE @@ -0,0 +1,28 @@ +Copyright (c) 2015, Vihar Malviya + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/README.md b/README.md index 25ef9f5..ecd6145 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,189 @@ -php-aria2 -========= -# talk with aria2 using json-RPC +# phpAria2rpc -## make sure aria2c is running -you can add below into /etc/rc.local -`/usr/local/bin/aria2c --enable-rpc --rpc-allow-origin-all -c -D` +[![Version][mg_BadgeVersion]][ln_ReleaseLatest] +[![Issues][mg_BadgeIssues]][ln_Issues] +[![Language][mg_BadgeCodeLang]][ln_CodeLang] +[![License][mg_BadgeLicense]][ln_License] +Library to communicate with aria2 using json-RPC. -> the document of aria2 is [here](http://aria2.sourceforge.net/manual/en/html/aria2c.html#rpc-interface) +Based on *[shiny](https://github.com/shiny)*'s *[php-aria2](https://github.com/shiny/php-aria2)*. -## How To -the php-aria2 is simple and just 31 lines. -### Examples - include 'aria2.class.php'; - $aria2 = new aria2('http://127.0.0.1:6800/jsonrpc'); //this value is the default value,you can leave it empty. - var_dump($aria2->getGlobalStat()); - var_dump($aria2->tellActive()); - var_dump($aria2->tellWaiting(0,1000)); - var_dump($aria2->tellStopped(0,1000)); - var_dump($aria2->addUri(array('https://www.google.com.hk/images/srpr/logo3w.png'),array( + +## Install + + +### Pre-requisites + +* PHP 5+ with cURL support +* Standard web framework (web server, etc.) +* Aria2 running in daemon mode either on the same host or on a different known host + + +### Download + + +#### Archive + +Get the release archives from [downloads][ln_ReleaseLatest] + + +#### Clone + +Clone repository. + +``` +git clone --recurse-submodules \ +https://github.com/viharm/phpAria2rpc.git +``` + +Remember to clone recursively (`--recurse-submodules`) to ensure cloning the submodules. + + +### Deploy + +Save the downloaded directory structure in your choice of path within your application (plugins, includes, etc.) + + +## Configure + +No specific configuration required yet. + + +## Usage + + +### Run Aria2 in daemon mode + +There are several recommended options for configuring *Aria2* however the minimum necessary to get started are... + +* `--enable-rpc` +* `--rpc-allow-origin-all` +* `-c` +* `-D` + +Assuming that the *Aria2* binary is in your execution path, run it with the above options... + +``` +aria2c --enable-rpc --rpc-allow-origin-all -c -D +``` + +To enable auto-start on most *Linux* systems, add the following in `/etc/rc.local` before the `exit` line... + +``` +/usr/local/bin/aria2c --enable-rpc --rpc-allow-origin-all -c -D +``` + + +### Use + + +#### Include the library in your application code + +``` +include 'phpAria2.class.inc.php'; +``` + +#### Create an instance + +``` +$aria2 = new aria2() ; +``` + +*phpAria2rpc* uses safe defaults for *Aria2* running on the same host as the script is running on. See advanced usage for custom configuration + + +#### Call Aria2 methods + +``` +var_dump($aria2->getGlobalStat()); +var_dump($aria2->tellActive()); +var_dump($aria2->tellWaiting(0,1000)); +var_dump($aria2->tellStopped(0,1000)); +var_dump($aria2->addUri(array('https://www.google.com.hk/images/srpr/logo3w.png'),array( 'dir'=>'/tmp', - ))); - var_dump($aria2->tellStatus('1')); - var_dump($aria2->removeDownloadResult('1')); - //and more ... +))); +var_dump($aria2->tellStatus('1')); +var_dump($aria2->removeDownloadResult('1')); +//and more ... +``` + +### Advanced usage + +Advanced configuration allows custom settings. Formulate a server configuration array + +``` +$server = array ( + 'host' => 'aria2.host.local' , + 'port' => '6800' , + 'rpcsecret' => 'aria2rpcsecrettoken' , + 'secure' => TRUE , + 'cacert' => '/path/to/ca-cert/on/host/running/phpAria2.pem' , + 'rpcuser' => 'legacyrpcusername' , + 'rpcpass' => 'legacyrpcpassword' +) ; +``` + +This array is passed as a parameter only once, whilst creating an instance of the class. + +``` +$aria2 = new aria2($$server) ; +``` + +*phpAria2rpc* inserts the correct value as per *Aria2*'s requirement. + +Further usage is normal, by calling *Aria2* methods against *phpAria2rpc*. + + +#### Secure RPC + +If *Aria2* is configured for secure RPC, then set the `secure` key value in the `$server` array to `TRUE`. + +If self-signed certificates are used, then the appropriate CA certificate will have to be copied over to the host running this library and its path specified in the `cacert` key value in the `$server` array. + + +#### RPC secret token + +If *Aria2* has been configured with a secret token on the RPC interface then this should be specified in the `rpcsecret` key value in the `$server` array. + + +#### Legacy RPC authentication + +*phpAria2rpc* can also be configured to connect to *Aria2* daemons with the legacy username/password authentication for the RPC interface. + +Please note that the use of this method of authentication is deprecated by the *Aria2* authors, however still supported by *phpAria2rpc* for compatibility with older versions of *Aria2* without the newer secret token authentication. + + +#### RPC username (legacy) + +Specify the RPC username in the `rpcuser` key value of the `$server` array. + -you can read [http://aria2.sourceforge.net/manual/en/html/aria2c.html#rpc-interface](the the document of aria2) +#### RPC password (legacy) -### Download a File +Specify the RPC password in the `rpcpass` key value of the `$server` array. - var_dump($aria2->addUri(array('https://www.google.com.hk/images/srpr/logo3w.png'),array( - 'dir'=>'/tmp', - ))); -[http://aria2.sourceforge.net/manual/en/html/aria2c.html#input-file](More Options is Here) +### Examples + + +#### Download a File + +``` + $addresult = $aria2->addUri ( array ( + 'https://www.google.com.hk/images/srpr/logo3w.png' + ) , + array('dir'=>'/tmp') + ) ) ; +``` -### Returned Data Examples -*Can't Download* +#### Returned Data + + +##### Can't Download + +``` array(3) { ["id"]=> string(1) "1" @@ -97,9 +243,12 @@ you can read [http://aria2.sourceforge.net/manual/en/html/aria2c.html#rpc-inter string(1) "0" } } +``` + -*Downloading (Active)* +##### Downloading (Active) +``` array(3) { ["id"]=> string(1) "1" @@ -187,9 +336,12 @@ you can read [http://aria2.sourceforge.net/manual/en/html/aria2c.html#rpc-inter string(1) "0" } } +``` -*Downloaded* - + +##### Downloaded + +``` array(3) { ["id"]=> string(1) "1" @@ -286,3 +438,113 @@ you can read [http://aria2.sourceforge.net/manual/en/html/aria2c.html#rpc-inter string(1) "0" } } +``` + +## Known limitations + +* *Aria2* does not set CA certificates, so for self-signed certificates, the CA cert file will have to be copied to the host running *phpAria2rpc*. + + +## Support + +Please refer to the documentation of *Aria2* + +* http://aria2.sourceforge.net/manual/en/html/aria2c.html#rpc-interface for RPC interface. +* http://aria2.sourceforge.net/manual/en/html/aria2c.html for general options. + +Debugging can be enabled by setting boolean `$GLOBALS['bl_DebugSwitch']` to `TRUE`. + +``` +$GLOBALS['bl_DebugSwitch'] = TRUE ; +``` + +For issues, queries, suggestions and comments please create an [issue/ticket][ln_Issues]. + + +## Contribute + +Please feel free to clone/fork and contribute via pull requests. Donations also welcome, simply create an [issue/ticket][ln_Issues]. + +Please make contact for more information. + + +## Development environment ## +Developed on.. + +* *Debian Wheezy* +* *Apache* 2.2 +* *PHP* 5.4 +* *Aria2* 1.15.1 and 1.18.8 + + +## Licence + +Licensed under the modified BSD (3-clause) license. + +A copy of the license is available... + +* in the enclosed [`LICENSE`][ln_License] file. +* at http://opensource.org/licenses/BSD-3-Clause + + +## References + + +### php-aria2 + +* `aria2.class.php` (2013-11-22) +* Available in the public domain at https://github.com/shiny/php-aria2 +* Author daijie (shiny) + + +## Credits + + +### Tools + + +#### Kint + +*Kint* debugging library (http://raveren.github.io/kint/), used under the MIT license + +Copyright (c) 2013 Rokas Å leinius (raveren at gmail dot com) + + +### Utilities + + +#### Codiad + +*Codiad* web based IDE (https://github.com/Codiad/Codiad), used under a MIT-style license. + +Copyright (c) Codiad & Kent Safranski (codiad.com) + + +#### SmartGit + +*SmartGit* client for *Git* (http://www.syntevo.com/smartgit/) used under SOFTWARE Non-Commercial License + +Copyright by syntevo GmbH + + +#### jEdit + +*jEdit* text editor (http://www.jedit.org/), used under the GNU GPL v2. + +Copyright (C) jEdit authors. + + +### GitHub + +Hosted by *GitHub* code repository (github.com). + + + +[mg_BadgeLicense]: https://img.shields.io/github/license/viharm/phpAria2rpc.svg?style=flat-square +[mg_BadgeVersion]: https://img.shields.io/github/release/viharm/phpAria2rpc.svg?style=flat-square +[mg_BadgeIssues]: https://img.shields.io/github/issues/viharm/phpAria2rpc.svg?style=flat-square +[mg_BadgeCodeLang]: https://img.shields.io/badge/language-php-yellowgreen.svg?style=flat-square +[ln_ReleaseLatest]: https://github.com/viharm/phpAria2rpc/releases/latest +[ln_License]: LICENSE?at=master +[ln_Issues]: https://github.com/viharm/phpAria2rpc/issues +[ln_CodeLang]: https://www.python.org/ diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..ef18c62 --- /dev/null +++ b/VERSION @@ -0,0 +1,2 @@ +02.00.00 +(2015-06-22) \ No newline at end of file diff --git a/aria2.class.php b/aria2.class.php deleted file mode 100644 index 0d54045..0000000 --- a/aria2.class.php +++ /dev/null @@ -1,31 +0,0 @@ -server = $server; - $this->ch = curl_init($server); - curl_setopt_array($this->ch, array( - CURLOPT_POST=>true, - CURLOPT_RETURNTRANSFER=>true, - CURLOPT_HEADER=>false - )); - } - function __destruct(){ - curl_close($this->ch); - } - private function req($data){ - curl_setopt($this->ch, CURLOPT_POSTFIELDS, $data); - return curl_exec($this->ch); - } - function __call($name, $arg){ - $data = array( - 'jsonrpc'=>'2.0', - 'id'=>'1', - 'method'=>'aria2.'.$name, - 'params'=>$arg - ); - $data = json_encode($data); - return json_decode($this->req($data), 1); - } -} diff --git a/phpAria2rpc.class.inc.php b/phpAria2rpc.class.inc.php new file mode 100644 index 0000000..d14599e --- /dev/null +++ b/phpAria2rpc.class.inc.php @@ -0,0 +1,207 @@ + '127.0.0.1' , + 'port' => '6800' , + 'rpcsecret' => NULL , + 'secure' => FALSE , + 'cacert' => NULL , + 'rpcuser' => NULL , + 'rpcpass' => NULL + ) + ) { + if (!function_exists('fn_Debug')) { function fn_Debug(){} } + + fn_Debug ( 'Server information' , $server , 'rpcpass' ) ; + $this->server = $server ; + fn_Debug ( 'transferred host string to private class variable, now applying default values' , $this->server , 'rpcpass' ) ; + if ( ! @array_key_exists ( 'host' , $this->server ) | @is_null($this->server['host']) ) { + $this->server['host'] = '127.0.0.1' ; + } + if ( ! @array_key_exists ( 'port' , $this->server ) | @is_null($this->server['port']) ) { + $this->server['port'] = 6800 ; + } + if ( ! @array_key_exists ( 'rpcsecret' , $this->server ) | @is_null($this->server['rpcsecret']) ) { + $this->server['rpcsecret'] = NULL ; + } + if ( ! @array_key_exists ( 'secure' , $this->server ) | @is_null($this->server['secure']) ) { + $this->server['secure'] = FALSE ; + } + if ( ! @array_key_exists ( 'cacert' , $this->server ) | @is_null($this->server['cacert']) ) { + $this->server['cacert'] = NULL ; + } + if ( ! @array_key_exists ( 'rpcuser' , $this->server ) | @is_null($this->server['rpcuser']) ) { + $this->server['rpcuser'] = NULL ; + } + if ( ! @array_key_exists ( 'rpcpass' , $this->server ) | @is_null($this->server['rpcpass']) ) { + $this->server['rpcpass'] = NULL ; + } + fn_Debug ( 'Default values set' , $this->server , 'rpcpass' ) ; + fn_Debug ( 'Checking if secure RPC connection is requested' , $this->server['secure'] ) ; + switch ($this->server['secure']) { + case TRUE : + fn_Debug ( 'Secure RPC connection is requested; setting prefix for connection string' ) ; + $connprefix = 'https://' ; + break ; + default : + fn_Debug ( 'Secure RPC connection is not requested; setting prefix for connection string' ) ; + $connprefix = 'http://' ; + } + fn_Debug ( 'protocol selected for Connection prefix, now checking if newer RPC secret is provided' , $connprefix ) ; + fn_Debug ( 'Checking legacy RPC credentials' , array ( $this->server['rpcuser'] , $this->server['rpcpass'] ) , 1 ) ; + if ( ! $this->server['rpcuser'] == NULL ) { + fn_Debug ( 'found username for legacy Aria2 RPC credentials, appending to connection prefix' , $this->server['rpcuser'] ) ; + $connprefix .= $this->server['rpcuser'] ; + fn_Debug ( 'Username appended to connection prefix, checking legacy password' , $connprefix ) ; + if ( ! $this->server['rpcpass'] == NULL ) { + fn_Debug ( 'found password for legacy Aria2 RPC credentials, appending to connection prefix' , $this->server['rpcpass'] , '' ) ; + $connprefix .= ':' . $this->server['rpcpass'] . '@' ; + fn_Debug ( 'password appended to connection prefix' , $connprefix , '' ) ; + } else { + fn_Debug ( 'Legacy RPC password not provided' ) ; + } + } else { + fn_Debug ( 'Legacy RPC user not provided. legacy RPC credentials skipped' ) ; + } + fn_Debug ( 'connection prefix complete. Formulating connection string' ) ; + $connstring = $connprefix . $this->server['host'] . ':' . $this->server['port'] . '/jsonrpc' ; + fn_Debug ( 'Connection string formulated, releasing prefix memory' , $connstring ) ; + unset($connprefix) ; + $this->ch = curl_init($connstring) ; + fn_Debug ( 'initiated curl; analysing errors' , $this->ch ) ; + fn_Debug ('error code' , curl_errno($this->ch) ) ; + fn_Debug ('error message' , curl_error($this->ch) ) ; + fn_Debug ( 'Checking if debugging is enabled' , $GLOBALS['bl_DebugSwitch'] ) ; + if ($GLOBALS['bl_DebugSwitch']===TRUE) { + $result = NULL ; + fn_Debug ( 'initialised result buffer' , $result ) ; + curl_setopt_array ( + $this->ch , + array ( + CURLOPT_VERBOSE => TRUE , + CURLOPT_CERTINFO => TRUE + ) + ) ; + fn_Debug ( 'Verbosity for curl options set; analysing errors ' , $result ) ; + fn_Debug ( 'error code' , curl_errno($this->ch) ) ; + fn_Debug ( 'error message' , curl_error($this->ch) ) ; + } + fn_Debug ( 'Setting primary curl options' ) ; + $result = NULL ; + fn_Debug ( 'initialised result buffer' , $result ) ; + $result = curl_setopt_array ( + $this->ch , + array ( + CURLOPT_POST => TRUE , + CURLOPT_RETURNTRANSFER => TRUE , + CURLOPT_HEADER => FALSE + ) + ) ; + fn_Debug ( 'Curl options set; analysing errors ' , $result ) ; + fn_Debug ('error code' , curl_errno($this->ch) ) ; + fn_Debug ('error message' , curl_error($this->ch) ) ; + fn_Debug ( 'Checking if CA certificate has been provided' , $this->server['cacert'] ) ; + if (!is_null($this->server['cacert'])) { + $result = NULL ; + fn_Debug ( 'initialised result buffer' , $result ) ; + curl_setopt_array ( + $this->ch , + array ( + CURLOPT_CAINFO => $this->server['cacert'] + ) + ) ; + fn_Debug ( 'CA cert for curl set; analysing errors ' , $result ) ; + fn_Debug ( 'error code' , curl_errno($this->ch) ) ; + fn_Debug ( 'error message' , curl_error($this->ch) ) ; + } + } + + function __destruct() { + fn_Debug ( 'closing connection' , $this->ch ) ; + curl_close($this->ch) ; + } + + private function req($data) { + fn_Debug ( 'formulating request via postfields' , $data ) ; + curl_setopt ( $this->ch , CURLOPT_POSTFIELDS , $data ) ; + fn_Debug ( 'postfields formulation error code' , curl_errno($this->ch) ) ; + fn_Debug ( 'postfields formulation error message' , curl_error($this->ch) ) ; + $result = NULL ; + fn_Debug ( 'initialised result buffer' , $result ) ; + $result = curl_exec($this->ch) ; + fn_Debug ( 'request sent, analysing errors' , $result ) ; + fn_Debug ( 'postfields formulation error code' , curl_errno($this->ch) ) ; + fn_Debug ( 'postfields formulation error message' , curl_error($this->ch) ) ; + + return $result ; + } + + function __call ( $name , $arg ) { + fn_Debug ( 'function called' , $name ) ; + fn_Debug ( 'arguments called' , $arg ) ; + fn_Debug ( 'checking for RPC secret' , $this->server['rpcsecret'] , '' ) ; + if ( ! $this->server['rpcsecret'] == NULL ) { + fn_Debug ( 'Non-null RPC secret value, pre-pending to supplied arguments' , $this->server['rpcsecret'] , '' ) ; + array_unshift ( + $arg , + 'token:' . $this->server['rpcsecret'] + ) ; + } + $data = array ( + 'jsonrpc' => '2.0' , + 'id' => '1' , + 'method' => 'aria2.' . $name , + 'params' => $arg + ) ; + fn_Debug ( 'array formulated' , $data ) ; + $data = json_encode($data) ; + fn_Debug ( 'array encoded to json, sending request' , $data ) ; + $result = NULL ; + fn_Debug ( 'initialised result buffer' , $result ) ; + $result = $this->req($data) ; + fn_Debug ( 'response received' , $result ) ; + fn_Debug ( 'Checking for success' ) ; + if ( $result === FALSE ) { + fn_Debug ( 'curl failed' , $result ) ; + } else { + fn_Debug ( 'curl response valid, decoding json' , $result ) ; + $result = json_decode ( $result , 1 ) ; + fn_Debug ( 'decoded json, returning result' , $result ) ; + } + return $result ; + } + + } +?> \ No newline at end of file