This object is used to retrieve a grid (list of records, recordset). The grids can be used to retrieve for example list of affiliates, list of transactions, list of campaigns, etc.
Constructor:
Gpf_Rpc_Gridrequest($className, $methodName, $session) - creates grid request object. You have to specify name of the class + method to execute, and valid session object.
Method name is usually “getRows”, class name depends on the grid you want to access.
Methods:
The following methods are available in all high level API grid classes.
addFilter($code, $operator, $value) – add filter to the data. You can use it to search in records, or get only the records that you want.
Parameters description:
$code variable is the name of column you want to filter, or text 'search' if you want to search in multiple columns.
$operator is comparison operator. It is one of the:
Text comparison:
=
IN
NOT IN
Gpf_Data_Filter::LIKE
Gpf_Data_Filter::NOT_LIKE
Gpf_Data_Filter::EQUALS
Gpf_Data_Filter::NOT_EQUALS
Date comparison:
Gpf_Data_Filter::DATE_EQUALS
Gpf_Data_Filter::DATE_GREATER
Gpf_Data_Filter::DATE_LOWER
Gpf_Data_Filter::DATE_EQUALS_GREATER
Gpf_Data_Filter::DATE_EQUALS_LOWER
Gpf_Data_Filter::DATERANGE_IS
Gpf_Data_Filter::TIME_EQUALS
Gpf_Data_Filter::TIME_GREATER
Gpf_Data_Filter::TIME_LOWER
Gpf_Data_Filter::TIME_EQUALS_GREATER
Gpf_Data_Filter::TIME_EQUALS_LOWER
Daterange comparison:
Gpf_Data_Filter::DATERANGE_IS
$value variable is the value of comparison. For text and date comparisons, it is normal value. If $operator is Gpf_Data_Filter::DATERANGE_IS, the value must be one of:
Gpf_Data_Filter::RANGE_TODAY
Gpf_Data_Filter::RANGE_YESTERDAY
Gpf_Data_Filter::RANGE_LAST_7_DAYS
Gpf_Data_Filter::RANGE_LAST_30_DAYS
Gpf_Data_Filter::RANGE_LAST_90_DAYS
Gpf_Data_Filter::RANGE_THIS_WEEK
Gpf_Data_Filter::RANGE_LAST_WEEK
Gpf_Data_Filter::RANGE_LAST_2WEEKS
Gpf_Data_Filter::RANGE_LAST_WORKING_WEEK
Gpf_Data_Filter::RANGE_THIS_MONTH
Gpf_Data_Filter::RANGE_LAST_MONTH
Gpf_Data_Filter::RANGE_THIS_YEAR
Gpf_Data_Filter::RANGE_LAST_YEAR
Please make sure you use the correct operator for the correct type of data. For example using '=' operator on the date field will not work.
Examples of setting grid request filter:
// example of text filter
$request->addFilter("lastname", "=", "smith");
// or
$request->addFilter("search", Gpf_Data_Filter::LIKE, "mit");
// or
$request->addFilter("firstname", "IN", "Mark,John,Martin");
// example of date filter
$request->addFilter("dateinserted", Gpf_Data_Filter::DATE_LOWER, "2008-11-01");
// example of daterange filter
$request->addFilter("dateinserted", Gpf_Data_Filter::DATERANGE_IS, Gpf_Data_Filter::RANGE_THIS_YEAR);
setLimit($offset, $limit) – sets limit of returned records to $limit, starting with 0. First parameter $offset is not supported since version 5.11.8.1, paging works automatically, depending on last row from previous loading. The maximum number of records that can be returned is 500.
Tip: Set the page size as high as your script can handle, up to the maximum of 500. Loading 500 records per request instead of 30 means fewer API calls for the same data. Do not request more than 500 — the server reduces the limit to 500, the first page then returns fewer records than requested, and a paging loop that compares getSize() with getLimit() would stop after the first page.
setSorting($sortBy, $ascending) – sets sort by by column $sortBy, and in ascending or descending order
sendNow() - sends request. If there was some problem, it throws an exception
getGrid() - if request was successful, it returns grid object (Gpf_Data_Grid).
Important: Always pass 0 as the first parameter of setLimit(). If a request sends an offset greater than 0, it fails with the error API: Using "offset" in grid requests is not allowed. This happens when an old PapApi.class.php file is used. To resolve it, download a new one in the merchant panel at Tools > Integration > API Integration > Download PAP API.
addParam() - gridRequest retrieve a grid with default columns (Default view in merchant panel). If you want retrieve other as default columns, you can define them in param 'columns'
// example of adding param 'columns'
$request->addParam('columns', new Gpf_Rpc_Array(array(array('id'), array('refid'), array('clicksRaw'), array('clicksUnique'))));
Example retrieving the first page of affiliates
//----------------------------------------------
// get recordset with list of affiliates
$request = new Gpf_Rpc_GridRequest("Pap_Merchants_User_AffiliatesGrid", "getRows", $session);
// sets the page size to 500 rows, which is the maximum per request
// the first parameter is an offset which is not used, always keep it at 0
$request->setLimit(0, 500);
// sets columns, use it only if you want retrieve other as default columns
$request->addParam('columns', new Gpf_Rpc_Array(array(array('id'), array('refid'), array('userid'), array('username'), array('firstname'), array('lastname'), array('rstatus'), array('dateinserted'), array('salesCount'), array('clicksRaw'), array('clicksUnique'))));
// send request
try {
$request->sendNow();
} catch(Exception $e) {
die("API call error: ".$e->getMessage());
}
// request was successful, get the recordset from the grid result
$recordset = $request->getGrid()->getRecordset();
// iterate through the records
foreach($recordset as $rec) {
echo 'Affiliate name: '.$rec->get('firstname').' '.$rec->get('lastname').'<br>';
}
Example retrieving list of all affiliates with paging
//----------------------------------------------
// get recordset with list of affiliates
$request = new Gpf_Rpc_GridRequest("Pap_Merchants_User_AffiliatesGrid", "getRows", $session);
// sets the page size to 500 rows, which is the maximum per request
// the first parameter is an offset which is not used, always keep it at 0
$request->setLimit(0, 500);
// sets columns, use it only if you want retrieve other as default columns
$request->addParam('columns', new Gpf_Rpc_Array(array(array('id'), array('refid'), array('userid'), array('username'), array('firstname'), array('lastname'), array('rstatus'), array('dateinserted'), array('salesCount'), array('clicksRaw'), array('clicksUnique'))));
// execute request in a loop to load all data
// sending the same request again returns the next page
do {
// send request
try {
$request->sendNow();
} catch(Exception $e) {
die("API call error: ".$e->getMessage());
}
// request was successful, get the grid result and its recordset
$recordset = $request->getGrid()->getRecordset();
// iterate through the records
foreach($recordset as $rec) {
echo 'Affiliate name: '.$rec->get('firstname').' '.$rec->get('lastname').'<br>';
}
} while ($recordset->getSize() == $request->getLimit());