Minor fix to sort parameter, add ga: prefix to string parameter passe…

…d (not array) and handle reverse sort

New 'filter' functionality - New $filter parameter on requestReportData between sort and start_date - may cause problems with existing implementations of gapi.class.php but this is the best place...

New filter process function to clean up the parameters and translate to Google Analytics compatible filters string.
New example showing use of filter.

example.filter.php

@@ -0,0 +1,62 @@
+<?php
+define('ga_email','youremail@email.com');
+define('ga_password','your password');
+define('ga_profile_id','your profile id');
+
+require 'gapi.class.php';
+
+$ga = new gapi(ga_email,ga_password);
+
+/**
+ * Note: OR || operators are calculated first, before AND &&.
+ * There are no brackets () for precedence and no quotes are
+ * required around parameters.
+ * 
+ * Do not use brackets () for precedence, these are only valid for 
+ * use in regular expressions operators!
+ * 
+ * The below filter represented in normal PHP logic would be:
+ * country == 'United States' && ( browser == 'Firefox || browser == 'Chrome')
+ */
+
+$filter = 'country == United States && browser == Firefox || browser == Chrome';
+
+$ga->requestReportData(ga_profile_id,array('browser','browserVersion'),array('pageviews','visits'),'-visits',$filter);
+?>
+<table>
+<tr>
+  <th>Browser &amp; Browser Version</th>
+  <th>Pageviews</th>
+  <th>Visits</th>
+</tr>
+<?php
+foreach($ga->getResults() as $result):
+?>
+<tr>
+  <td><?php echo $result ?></td>
+  <td><?php echo $result->getPageviews() ?></td>
+  <td><?php echo $result->getVisits() ?></td>
+</tr>
+<?php
+endforeach
+?>
+</table>
+
+<table>
+<tr>
+  <th>Total Results</th>
+  <td><?php echo $ga->getTotalResults() ?></td>
+</tr>
+<tr>
+  <th>Total Pageviews</th>
+  <td><?php echo $ga->getPageviews() ?>
+</tr>
+<tr>
+  <th>Total Visits</th>
+  <td><?php echo $ga->getVisits() ?></td>
+</tr>
+<tr>
+  <th>Results Updated</th>
+  <td><?php echo $ga->getUpdated() ?></td>
+</tr>
+</table>

gapi.class.php

@@ -89,7 +89,7 @@ public function requestAccountData($start_index=1, $max_results=20)
     }
     else 
     {
-      throw new Exception('GAPI: Failed to request account data. Error: "' . $response['body'] . '"');
+      throw new Exception('GAPI: Failed to request account data. Error: "' . strip_tags($response['body']) . '"');
     }
   }
 
@@ -104,12 +104,13 @@ public function requestAccountData($start_index=1, $max_results=20)
    * @param Array $dimensions Google Analytics dimensions e.g. array('browser')
    * @param Array $metrics Google Analytics metrics e.g. array('pageviews')
    * @param Array $sort_metric OPTIONAL: Dimension or dimensions to sort by e.g.('-visits')
+   * @param String $filter OPTIONAL: Filter logic for filtering results
    * @param String $start_date OPTIONAL: Start of reporting period
    * @param String $end_date OPTIONAL: End of reporting period
    * @param Int $start_index OPTIONAL: Start index of results
    * @param Int $max_results OPTIONAL: Max results returned
    */
-  public function requestReportData($report_id, $dimensions, $metrics, $sort_metric=null, $start_date=null, $end_date=null, $start_index=1, $max_results=30)
+  public function requestReportData($report_id, $dimensions, $metrics, $sort_metric=null, $filter=null, $start_date=null, $end_date=null, $start_index=1, $max_results=30)
   {
     $parameters = array('ids'=>'ga:' . $report_id);
 
@@ -166,7 +167,23 @@ public function requestReportData($report_id, $dimensions, $metrics, $sort_metri
     }
     else 
     {
-      $parameters['sort'] = $sort_metric;
+      if (substr($sort_metric, 0, 1) == "-")
+      {
+        $parameters['sort'] = '-ga:' . substr($sort_metric, 1);
+      }
+      else 
+      {
+        $parameters['sort'] = 'ga:' . $sort_metric;
+      }
+    }
+
+    if($filter!=null)
+    {
+      $filter = $this->processFilter($filter);
+      if($filter!==false)
+      {
+        $parameters['filters'] = $filter;
+      }
     }
 
     if($start_date==null)
@@ -198,7 +215,34 @@ public function requestReportData($report_id, $dimensions, $metrics, $sort_metri
     }
     else 
     {
-      throw new Exception('GAPI: Failed to request report data. Error: "' . $response['body'] . '"');
+      throw new Exception('GAPI: Failed to request report data. Error: "' . strip_tags($response['body']) . '"');
+    }
+  }
+
+  /**
+   * Process filter string, clean parameters and convert to Google Analytics
+   * compatible format
+   * 
+   * @param String $filter
+   * @return String Compatible filter string
+   */
+  protected function processFilter($filter)
+  {
+    $valid_operators = '(!~|=~|==|!=|>|<|>=|<=|=@|!@)';
+
+    $filter = preg_replace('/\s\s+/',' ',trim($filter)); //Clean duplicate whitespace
+    $filter = str_replace(array(',',';','\\'),array('\,','\;','\\\\'),$filter); //Escape Google Analytics reserved characters
+    $filter = preg_replace('/(&&\s*|\|\|\s*|^)([a-z]+)(\s*' . $valid_operators . ')/i','$1ga:$2$3',$filter); //Prefix ga: to metrics and dimensions
+    $filter = preg_replace('/[\'\"]/i','',$filter); //Clear invalid quote characters
+    $filter = preg_replace(array('/\s*&&\s*/','/\s*\|\|\s*/','/\s*' . $valid_operators . '\s*/'),array(';',',','$1'),$filter); //Clean up operators
+
+    if(strlen($filter)>0)
+    {
+      return urlencode($filter);
+    }
+    else 
+    {
+      return false;
     }
   }
 
@@ -351,7 +395,7 @@ protected function authenticateUser($email, $password)
 
     if(substr($response['code'],0,1) != '2' || !is_array($auth_token) || empty($auth_token['Auth']))
     {
-      throw new Exception('GAPI: Failed to authenticate user. Error: "' . $response['body'] . '"');
+      throw new Exception('GAPI: Failed to authenticate user. Error: "' . strip_tags($response['body']) . '"');
     }
 
     $this->auth_token = $auth_token['Auth'];