File: documentation/CLI.txt

+----------------------------+
|---------+ INTRO +----------|
+----------------------------+

There is a commandline interface to the paypal api provided with this package, 
consisting of three classes (which can be discarded if no cli use is required):

SnPayPalCli
SnPayPalCliMethod (abstract)
SnPayPalCliMethods

The /Methods class provides a means to:
* get an account balance
	php cli cb [nodays=(int)]

* get one days worth of transactions (payments received)
	php cli lt

* get one weeks worth of withdrawl transactions
	php cli fw

* get X days of X type of transactions
	php cli gt [nodays=(int) type=(r||w)]

You will need to modify the code a little to add more types that withdrawl/received (see below)

(Explanation of the commandline arguments supplied are available from the function comments themselevs.)

You can extend from SnPayPalMethods and add your own commandline commands, or add functions directly to that class,
The former is recommended, as updates may overwrite modifications to the file.


+----------------------------+
|------+ WIN INSTALL +-------|
+----------------------------+

On windows you will need to add php to your path to use the example cli arguments provided,
Go to the Properties of My Computer (or startmenu->Computer on vista) 
Then advanced/advanced system settings -> environmental variables
Scroll down to PATH, Edit then add ;Drive:\Path\to\PHP\

When this is done go to startmenu->run (windows key + R) and type cmd
At the command prompt type: start .
This will open a folder, place all the files of this archive in that folder (hide them by file properties->check hidden; recommended)
Check everything works by opening run once more and typing php cli info
if that doesnt work but: php -r "echo 'PHP WORKS! Press enter to exit!'; fgets(STDIN, 250);"
does then it is a problem with the location of the files extracted, if not you havent added php to your path properly.
NB: the file cli should be at the exact location of "start ."



+----------------------------+
|-----+ LINUX INSTALL +------|
+----------------------------+

Linux users simply need to extract the files to the home folder (the default folder at the prompt, type pwd to find where that is)

+---------------------------------------+
|---+ ADDING YOUR OWN CLI FUNCTION +----|
+---------------------------------------+

All functions should take the form, public function myFunctionName($cli, $paypal, $eventArgs)
The last variable, $eventArgs is a hold over from a different implementation, a better name would be $cmdArgs, 
but i'm keeping with convention, executed commands are still events in any case.

In this example we can look at another predefined SnPayPalApi Method: refundTransaction($transactionId)

Use $cli->write() to send output to the console window, and $eventArgs to acccess cli arguments,
We will implement the function so the user sends tid=xxx as an argument, e.g.

php cli refund tid=123456

(Notice the name 'refund' we will add this to the list of available functions later)

$paypal can be used to access the PayPal API methods defined in SnPayPalApi (/ApiInterface)

public function refundTransaction($cli, $paypal, $eventArgs)
{
	$cli->write('Transaction ID: ' . $eventArgs->tid;
	if($response = $paypal->refundTransaction($eventArgs->tid)->getResponse('RefundTransactionRequest'))
	{
		$cli->write('Refund Amout: ' . $response->FeeRefundAmount);
		return true;
	}

	else return false;
}

If $this->disableAutoOutput() isnt called, SnCliPayPal will format your output and send some extra information,
such as whether the command failed or not, it will make this judgement on the boolean value returned, false = fail.


NB: This function hasnt been tested and will likely need fine-tuning, I used the enclosed API Reference for response field names,
as opposed to print_r'ing the soap response. You can send print_r output to the command line using,

$cli->write(print_r($Variable, true));
it may be best to call $this->disableAutoOutput();

When you have written your function you need to add it to the available command list, you do this by implementing the function getCliCommands,

public function getCliCommands()
{
	$cmds = parent::getCliCommands();
	$cmds['refund'] = 'refundTransaction';
	return $cmds;
}

You need to call parent::getCliCommands() to preserve the existing commands of SnPayPalCliMethods, which you should be extending from, 
if you decide to alter the existing class you should just add another key to the existing array,
   
    /**
     * Return the commands made available by this class
     *
     * @return array
     */
    public function getCliCommands()
    {
        $commads = array();
        
        $commads['info'] = 'info'; 
        $commads['pa']   = 'printArgs'; 
        $commads['cb']   = 'checkBalance'; 
        $commads['fw']   = 'getWithdrawlTransactions';
        $commads['lt']   = 'getLatestTransactions';
        $commads['gt']   = 'getTransactions';
        $commads['refund']   = 'refundTransaction';
    }

NOTE: Several of PayPal API functions are implemented in SnPayPalApi, but not all, still left to implement are:
* Authorization and Capture
* Direct Payment
* Express Checkout

However implementing these APIs is not a difficult task using the prebuild callApi() methods and SnPayPalParameter-s,
see API.txt for more information.

+---------------------------------------+
|-----+ ADDING TRANSACTION TYPES +------|
+---------------------------------------+

Inside SnPayPalMethods there is:

    /**
     * Return a list of transactions, options from the cmdline:
     * nodays=number_of_days_to_search_from_today
     * type=r||w - funds received or withdrawls
     * 
     * @example php cli gt nodays=7 type=r
     * @param SnCliPayPal $cli
     * @param SnPayPalApi $paypal
     * @param stdClass $eventArgs
     * @return boolean
     */
    public function getTransactions($cli, $paypal, $eventArgs)
    {
        $cmdArg = array('w' => SnPayPalApiConst::TRANS_CLASS_WITHDRAWN,
                        'r' => SnPayPalApiConst::TRANS_CLASS_RECEIVED);

to add more types, e.g. the PayPal TransactionClass 'All',

    public function getTransactions($cli, $paypal, $eventArgs)
    {
        $cmdArg = array('w' => SnPayPalApiConst::TRANS_CLASS_WITHDRAWN,
                        'r' => SnPayPalApiConst::TRANS_CLASS_RECEIVED
                        'a' => SnPayPalApiCOnst::TRANS_CLASS_ALL);

Then from the cmd line, php cli gt type=a nodays=7
For a week of all transactions.