Added sorting/filtering support and also modified ListFeed to provide data exactly as supplied by google without any processing

Author: asimlqt

README.md

@@ -4,7 +4,7 @@ This library provides a simple interface to the Google Spreadsheet API.
 
 There are a couple of important things to note.
 
-* This library requires a valid OAuth access token to work but does not provide any means of generating one. The [Google APIs Client Library for PHP](https://github.com/google/google-api-php-client) has all the functionality required for for generating and refreshing tokens so it would have been a waste of time duplicating the official google library.
+* This library requires a valid OAuth access token to work but does not provide any means of generating one. The [Google APIs Client Library for PHP](https://github.com/google/google-api-php-client) has all the functionality required for for generating and refreshing tokens so it would have been a waste of time duplicating the official google library. I have created a demo application which shows how to generate an OAuth token [here](https://github.com/asimlqt/php-google-oauth).
 * You can not create spreadsheets using this (PHP Google Spreadsheet Client) library, as creating spreadsheets is not part of the Spreadsheet API and the functionality already exists in the official Google Client Library.
 
 I strongly recommend you read through the [official Google Spreadsheet API documentation](https://developers.google.com/google-apps/spreadsheets) to get a grasp of the concepts.
@@ -20,7 +20,7 @@ Using [composer](https://getcomposer.org/) is the recommended way to install it.
 ```json
 {
     "require": {
-        "asimlqt/php-google-spreadsheet-client": "2.2.*"
+        "asimlqt/php-google-spreadsheet-client": "2.3.*"
     }
 }
 ```
@@ -131,6 +131,17 @@ foreach ($listFeed->getEntries() as $entry) {
 
 The getValues() method returns an associative array where the keys are the column names and the values are the cell content.
 
+> Note: The Google api converts the column headers to lower case so the column headings might not appear to be the same as what you see in Google Drive using your browser. 
+
+> Note: If there is data for a particular row which does not have a column header then Google randomly generates a header and as far as i know it always begins with an underscore. Bear in mind that this is not generated by this library.
+
+You can also sort and filter the data so you only retrieve what is required, this is expecially useful for large worksheets.
+
+```php
+$listFeed = $worksheet->getListFeed(array("sq" => "age > 45", "reverse" => "true"));
+```
+To find out all the available options visit [https://developers.google.com/google-apps/spreadsheets/#sorting_rows](https://developers.google.com/google-apps/spreadsheets/#sorting_rows).
+
 ### Adding a list row
 
 ```php
@@ -145,6 +156,8 @@ $row = array('name'=>'John', 'age'=>25);
 $listFeed->insert($row);
 ```
 
+> When adding or updating a row the column headers need to match exactly what was returned by the Google API, not what you see in Google Drive.
+
 ### Updating a list row
 
 ```php

src/Google/Spreadsheet/ListFeed.php

@@ -37,7 +37,7 @@ class ListFeed
     /**
      * Constructor
      * 
-     * @param string $xmlStr
+     * @param string $xmlString
      */
     public function __construct($xmlString)
     {
@@ -89,44 +89,18 @@ public function getEntries()
         $rows = array();
 
         if(count($this->xml->entry) > 0) {
-            $colNames = $this->getColumnNames($this->xml);
-            $colNamesCount = count($colNames);
 
             foreach ($this->xml->entry as $entry) {
-                $cols = $entry->xpath('gsx:*');
-                $vals = array();
-                
-                foreach($cols as $col) {
-                    $vals[] = $col->__toString();
-                }
-                
-                if(count($vals) < $colNamesCount) {
-                    $vals = array_pad($vals, $colNamesCount, null);
+                $data = array();
+                foreach($entry->xpath('gsx:*') as $col) {
+                    $data[$col->getName()] = $col->__toString();
                 }
 
-                $rows[] = new ListEntry($entry, array_combine($colNames, $vals));
+                $rows[] = new ListEntry($entry, $data);
             }
         }
+        
         return $rows;
     }
 
-    /**
-     * Get the column names
-     * 
-     * @param \SimpleXMLElement $xml
-     * 
-     * @return array
-     */
-    public function getColumnNames(SimpleXMLElement $xml = null)
-    {
-        if($xml === null) {
-            $xml = $this->xml;
-        }
-		
-        $ret = array();
-        foreach($xml->entry->xpath('gsx:*') as $col) {
-            $ret[] = $col->getName();
-        }
-        return $ret;
-    }
-}
+}

src/Google/Spreadsheet/Worksheet.php

@@ -105,11 +105,18 @@ public function getColCount()
     /**
      * Get the list feed of this worksheet
      * 
+     * @param array $query add additional query params to the url to sort/filter the results
+     * 
      * @return \Google\Spreadsheet\List\Feed
      */
-    public function getListFeed()
+    public function getListFeed(array $query = array())
     {
-        $res = ServiceRequestFactory::getInstance()->get($this->getListFeedUrl());
+        $feedUrl = $this->getListFeedUrl();
+        if(count($query) > 0) {
+            $feedUrl .= "?" . http_build_query($query);
+        }
+        
+        $res = ServiceRequestFactory::getInstance()->get($feedUrl);
         return new ListFeed($res);
     }
 

tests/Google/Spreadsheet/WorksheetTest.php

@@ -31,4 +31,46 @@ public function testGetTitle()
         $this->assertEquals('Test', $worksheet->getTitle());
     }
 
-}
+    public function testGetListFeedDefault()
+    {
+        $feedUrl = "https://spreadsheets.google.com/feeds/list/tA3TdJ0RIVEem3xQZhG2Ceg/od8/private/full";
+        
+        $mockServiceRequest = $this->getMockBuilder('Google\Spreadsheet\DefaultServiceRequest')
+                ->setMethods(array("get"))
+                ->disableOriginalConstructor()
+                ->getMock();
+        
+        $mockServiceRequest
+            ->expects($this->once())
+            ->method('get')
+            ->with($this->equalTo($feedUrl))
+            ->willReturn(file_get_contents(__DIR__.'/xml/list-feed.xml'));
+        
+        ServiceRequestFactory::setInstance($mockServiceRequest);
+        
+        $worksheet = new Worksheet(new SimpleXMLElement(file_get_contents(__DIR__.'/xml/worksheet.xml')));
+        $worksheet->getListFeed();
+    }
+    
+    public function testGetListFeedWithQuery()
+    {
+        $feedUrl = "https://spreadsheets.google.com/feeds/list/tA3TdJ0RIVEem3xQZhG2Ceg/od8/private/full?reverse=true&sq=age+%3E+45";
+        
+        $mockServiceRequest = $this->getMockBuilder('Google\Spreadsheet\DefaultServiceRequest')
+                ->setMethods(array("get"))
+                ->disableOriginalConstructor()
+                ->getMock();
+        
+        $mockServiceRequest
+            ->expects($this->once())
+            ->method('get')
+            ->with($this->equalTo($feedUrl))
+            ->willReturn(file_get_contents(__DIR__.'/xml/list-feed.xml'));
+        
+        ServiceRequestFactory::setInstance($mockServiceRequest);
+        
+        $worksheet = new Worksheet(new SimpleXMLElement(file_get_contents(__DIR__.'/xml/worksheet.xml')));
+        $worksheet->getListFeed(array("reverse" => "true", "sq" => "age > 45"));
+    }
+    
+}