- added more examples

- phpdoc fixes
- zendhttp bugfix

examples/4.1-api-usage.php

+<?php
+
+require('init.php');
+htmlHeader();
+
+// create a client instance
+$client = new Solarium_Client($config);
+
+// get a select query instance
+$query = $client->createSelect();
+
+// apply settings using the API
+$query->setQuery('*:*');
+$query->setStart(2)->setRows(20);
+$query->setFields(array('id','name','price'));
+$query->addSort('price', Solarium_Query_Select::SORT_ASC);
+
+// create a filterquery using the API
+$fq = $query->createFilterQuery();
+$fq->setKey('maxprice');
+$fq->setQuery('price:[1 TO 300]');
+// and add it to the query
+$query->addFilterQuery($fq);
+
+// create a facet field instance and set options using the API
+$facetSet = $query->getFacetSet();
+$facet = $facetSet->createFacetField();
+$facet->setKey('stock');
+$facet->setField('inStock');
+$facetSet->addFacet($facet);
+
+// this executes the query and returns the result
+$resultset = $client->select($query);
+
+// display the total number of documents found by solr
+echo 'NumFound: '.$resultset->getNumFound();
+
+// display facet counts
+echo '<hr/>Facet counts for field "inStock":<br/>';
+$facet = $resultset->getFacetSet()->getFacet('stock');
+foreach($facet as $value => $count) {
+    echo $value . ' [' . $count . ']<br/>';
+}
+
+// show documents using the resultset iterator
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+    echo '<tr><th>id</th><td>' . $document->id . '</td></tr>';
+    echo '<tr><th>name</th><td>' . $document->name . '</td></tr>';
+    echo '<tr><th>price</th><td>' . $document->price . '</td></tr>';
+    echo '</table>';
+}
+
+htmlFooter();
\ No newline at end of file

examples/4.2-configuration-usage.php

+<?php
+
+require('init.php');
+htmlHeader();
+
+
+// In this case an array is used for configuration to keep the example simple.
+// For an easier to use config file you are probably better of with another format, like Zend_Config_Ini
+// See the documentation for more info about this.
+$select = array(
+    'query'         => '*:*',
+    'start'         => 2,
+    'rows'          => 20,
+    'fields'        => array('id','name','price'),
+    'sort'          => array('price' => 'asc'),
+    'filterquery' => array(
+        'maxprice' => array(
+            'query' => 'price:[1 TO 300]'
+        ),
+    ),
+    'component' => array(
+        'facetset' => array(
+            'facet' => array(
+                // notice this config uses an inline key value, instead of array key like the filterquery
+                array('type' => 'field', 'key' => 'stock', 'field' => 'inStock'),
+            )
+        ),
+    ),
+);
+
+// create a client instance
+$client = new Solarium_Client($config);
+
+// get a select query instance based on the config
+$query = $client->createSelect($select);
+
+// this executes the query and returns the result
+$resultset = $client->select($query);
+
+// display the total number of documents found by solr
+echo 'NumFound: '.$resultset->getNumFound();
+
+// display facet counts
+echo '<hr/>Facet counts for field "inStock":<br/>';
+$facet = $resultset->getFacetSet()->getFacet('stock');
+foreach($facet as $value => $count) {
+    echo $value . ' [' . $count . ']<br/>';
+}
+
+// show documents using the resultset iterator
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+    echo '<tr><th>id</th><td>' . $document->id . '</td></tr>';
+    echo '<tr><th>name</th><td>' . $document->name . '</td></tr>';
+    echo '<tr><th>price</th><td>' . $document->price . '</td></tr>';
+    echo '</table>';
+}
+
+htmlFooter();
\ No newline at end of file

examples/4.3-extending-usage.php

+<?php
+
+require('init.php');
+htmlHeader();
+
+// In most cases using the API or config is advisable, however in some cases it can make sense to extend classes.
+// This makes it possible to create 'query inheritance' like in this example
+class ProductQuery extends Solarium_Query_Select{
+
+    protected function _init()
+    {
+        parent::_init();
+
+        // basic params
+        $this->setQuery('*:*');
+        $this->setStart(2)->setRows(20);
+        $this->setFields(array('id','name','price'));
+        $this->addSort('price', Solarium_Query_Select::SORT_ASC);
+
+        // create a facet field instance and set options
+        $facetSet = $this->getFacetSet();
+        $facet = $facetSet->createFacetField();
+        $facet->setKey('stock');
+        $facet->setField('inStock');
+        $facetSet->addFacet($facet);
+    }
+
+}
+
+// This query inherits all of the query params of it's parent (using parent::_init) and adds some more
+// Ofcourse it could also alter or remove settings
+class ProductPriceLimitedQuery extends ProductQuery{
+
+    protected function _init()
+    {
+        parent::_init();
+
+        // create a filterquery
+        $fq = $this->createFilterQuery();
+        $fq->setKey('maxprice');
+        $fq->setQuery('price:[1 TO 300]');
+        // and add it
+        $this->addFilterQuery($fq);
+
+    }
+
+}
+
+// create a client instance
+$client = new Solarium_Client($config);
+
+// create a query instance
+$query = new ProductPriceLimitedQuery;
+
+// this executes the query and returns the result
+$resultset = $client->select($query);
+
+// display the total number of documents found by solr
+echo 'NumFound: '.$resultset->getNumFound();
+
+// display facet counts
+echo '<hr/>Facet counts for field "inStock":<br/>';
+$facet = $resultset->getFacetSet()->getFacet('stock');
+foreach($facet as $value => $count) {
+    echo $value . ' [' . $count . ']<br/>';
+}
+
+// show documents using the resultset iterator
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+    echo '<tr><th>id</th><td>' . $document->id . '</td></tr>';
+    echo '<tr><th>name</th><td>' . $document->name . '</td></tr>';
+    echo '<tr><th>price</th><td>' . $document->price . '</td></tr>';
+    echo '</table>';
+}
+
+htmlFooter();
\ No newline at end of file

examples/5.2-extending.php

+<?php
+
+require('init.php');
+htmlHeader();
+
+// This is a custom query class that could have some customized logic
+class MyQuery extends Solarium_Query_Select
+{
+    // ...customization here...
+}
+
+// And this is the extended client, that modifies the default query mapping
+// for select queries to our custom query class.
+// BTW, the same could also be done using a plugin, see example 5.3.2
+class MyClient extends Solarium_Client
+{
+     /**
+     * Querytype mappings
+     */
+    protected $_queryTypes = array(
+        self::QUERYTYPE_SELECT => array(
+            'query'          => 'MyQuery',
+            'requestbuilder' => 'Solarium_Client_RequestBuilder_Select',
+            'responseparser' => 'Solarium_Client_ResponseParser_Select'
+        ),
+        self::QUERYTYPE_UPDATE => array(
+            'query'          => 'Solarium_Query_Update',
+            'requestbuilder' => 'Solarium_Client_RequestBuilder_Update',
+            'responseparser' => 'Solarium_Client_ResponseParser_Update'
+        ),
+        self::QUERYTYPE_PING => array(
+            'query'          => 'Solarium_Query_Ping',
+            'requestbuilder' => 'Solarium_Client_RequestBuilder_Ping',
+            'responseparser' => 'Solarium_Client_ResponseParser_Ping'
+        ),
+    );
+}
+
+
+// create a client instance
+$client = new MyClient($config);
+
+// create a select query instance
+$query = $client->createSelect();
+
+// check the query class, it should be our custom query class
+echo 'Query class: ' . get_class($query) . '<br/>';
+
+// execute query
+$result = $client->execute($query);
+
+// display the total number of documents found by solr
+echo 'NumFound: '.$result->getNumFound();
+
+// show documents using the resultset iterator
+foreach ($result as $document) {
+
+    echo '<hr/><table>';
+
+    // the documents are also iterable, to get all fields
+    foreach($document AS $field => $value)
+    {
+        // this converts multivalue fields to a comma-separated string
+        if(is_array($value)) $value = implode(', ', $value);
+        
+        echo '<tr><th>' . $field . '</th><td>' . $value . '</td></tr>';
+    }
+
+    echo '</table>';
+}
+
+htmlFooter();
\ No newline at end of file

examples/5.3.1-plugin-event-hooks.php

@@ -9,7 +9,7 @@ class basicDebug extends Solarium_Plugin_Abstract
     protected $_start;
     protected $_output = array();
 
-    public function __construct()
+    public function _initPlugin()
     {
         $this->_start = microtime(true);
     }

examples/5.3.2-plugin-solarium-presets.php

+<?php
+require('init.php');
+
+// This is a custom query class that could have some customized logic
+class MyQuery extends Solarium_Query_Select
+{
+    // ...customization here...
+}
+
+// this very simple plugin that modifies the default querytype mapping
+class queryCustomizer extends Solarium_Plugin_Abstract
+{
+
+    protected function _initPlugin()
+    {
+        $this->_client->registerQueryType(
+            Solarium_Client::QUERYTYPE_SELECT,
+            'MyQuery',
+            'Solarium_Client_RequestBuilder_Select',
+            'Solarium_Client_ResponseParser_Select'
+        );
+    }
+    
+}
+
+
+htmlHeader();
+
+// create a client instance and register the plugin
+$client = new Solarium_Client($config);
+$client->registerPlugin('querycustomizer', 'queryCustomizer');
+
+// create a select query instance
+$query = $client->createSelect();
+
+// check the query class, it should be our custom query class
+echo 'Query class: ' . get_class($query) . '<br/>';
+
+// execute the query and display the results
+$resultset = $client->select($query);
+echo 'NumFound: '.$resultset->getNumFound();
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+
+    foreach($document AS $field => $value)
+    {
+        if(is_array($value)) $value = implode(', ', $value);
+
+        echo '<tr><th>' . $field . '</th><td>' . $value . '</td></tr>';
+    }
+
+    echo '</table>';
+}
+
+htmlFooter();
\ No newline at end of file

examples/6.1-zend-http-adapter.php

+<?php
+
+require_once 'Zend/Loader/Autoloader.php';
+$loader = Zend_Loader_Autoloader::getInstance();
+
+require('init.php');
+htmlHeader();
+
+// create a client instance
+$client = new Solarium_Client($config);
+
+// set the adapter to zendhttp and get a zendhttp client instance reference
+$client->setAdapter('Solarium_Client_Adapter_ZendHttp');
+$zendHttp = $client->getAdapter()->getZendHttp();
+
+// you can use any of the zend_http features, like http-authentication
+$zendHttp->setAuth('user', 'password!', Zend_Http_Client::AUTH_BASIC);
+
+// get a select query instance
+$query = $client->createSelect();
+
+// this executes the query and returns the result
+$resultset = $client->select($query);
+
+// display the total number of documents found by solr
+echo 'NumFound: '.$resultset->getNumFound();
+
+// show documents using the resultset iterator
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+
+    // the documents are also iterable, to get all fields
+    foreach($document AS $field => $value)
+    {
+        // this converts multivalue fields to a comma-separated string
+        if(is_array($value)) $value = implode(', ', $value);
+        
+        echo '<tr><th>' . $field . '</th><td>' . $value . '</td></tr>';
+    }
+
+    echo '</table>';
+}
+
+htmlFooter();
\ No newline at end of file

examples/6.2-escaping.php

+<?php
+
+require('init.php');
+htmlHeader();
+
+// create a client instance
+$client = new Solarium_Client($config);
+
+// get a select query instance
+$query = $client->createSelect();
+
+// search input string, this value fails without escaping because of the double-quote
+$input = 'ATA "133';
+
+// in this case phrase escaping is used (most common) but you can also do term escaping, see the manual
+$query->setQuery('features:' . Solarium_Escape::phrase($input));
+
+// this executes the query and returns the result
+$resultset = $client->select($query);
+
+// display the total number of documents found by solr
+echo 'NumFound: '.$resultset->getNumFound();
+
+// show documents using the resultset iterator
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+
+    // the documents are also iterable, to get all fields
+    foreach($document AS $field => $value)
+    {
+        // this converts multivalue fields to a comma-separated string
+        if(is_array($value)) $value = implode(', ', $value);
+        
+        echo '<tr><th>' . $field . '</th><td>' . $value . '</td></tr>';
+    }
+
+    echo '</table>';
+}
+
+htmlFooter();
\ No newline at end of file

examples/6.3-demo-app.php

+<?php
+
+require('init.php');
+htmlHeader();
+
+echo 'TODO';
+
+htmlFooter();
\ No newline at end of file

library/Solarium/Autoloader.php

@@ -40,7 +40,7 @@
  *
  * This class is included to allow for easy usage of Solarium. If you already
  * have your own autoloader that follows the Zend Framework class/file naming
- * you don't need this.
+ * you can use that to autoload Solarium (for instance Zend_Loader).
  *
  * @package Solarium
  */

library/Solarium/Client.php

@@ -40,14 +40,15 @@
 /**
  * Main interface for interaction with Solr
  *
- * The client holds the Solr connection settings and uses an adapter instance to
- * execute queries and return the results. This is the main interface for any
- * user of the Solarium library.
+ * The client is the main interface for usage of the Solarium library.
+ * You can use it to get query instances and to execute them.
+ * It also allows to register plugins and querytypes to customize Solarium.
+ * Finally, it also gives access to the adapter, which holds the Solr connection settings.
  *
  * Example usage with default settings:
  * <code>
  * $client = new Solarium_Client;
- * $query = new Solarium_Query_Select;
+ * $query = $client->createSelect();
  * $result = $client->select($query);
  * </code>
  *
@@ -67,9 +68,6 @@ class Solarium_Client extends Solarium_Configurable
     /**
      * Default options
      *
-     * The defaults match a standard Solr example instance as distributed by
-     * the Apache Lucene Solr project.
-     *
      * @var array
      */
     protected $_options = array(
@@ -78,6 +76,8 @@ class Solarium_Client extends Solarium_Configurable
 
     /**
      * Querytype mappings
+     *
+     * These can be customized using {@link registerQueryType()}
      */
     protected $_queryTypes = array(
         self::QUERYTYPE_SELECT => array(
@@ -221,7 +221,9 @@ class Solarium_Client extends Solarium_Configurable
     /**
      * Register a querytype
      *
-     * You can also use this method to override any existing querytype with a new mapping
+     * You can also use this method to override any existing querytype with a new mapping.
+     * This requires the availability of the classes through autoloading or a manual
+     * require before calling this method.
      *
      * @param string $type
      * @param string $query
@@ -274,8 +276,12 @@ class Solarium_Client extends Solarium_Configurable
     /**
      * Register a plugin
      *
+     * You can supply a plugin instance or a plugin classname as string.
+     * This requires the availability of the class through autoloading
+     * or a manual require.
+     *
      * @param string $key
-     * @param string|object $plugin
+     * @param string|Solarium_Plugin_Abstract $plugin
      * @param array $options
      * @return Solarium_Client Provides fluent interface
      */
@@ -332,7 +338,7 @@ class Solarium_Client extends Solarium_Configurable
      * Get a plugin instance
      *
      * @param string $key
-     * @return array|null
+     * @return Solarium_Plugin_Abstract|null
      */
     public function getPlugin($key)
     {
@@ -379,8 +385,6 @@ class Solarium_Client extends Solarium_Configurable
     /**
      * Creates a request based on a query instance
      *
-     * @todo add caching of request builder?
-     *
      * @param Solarium_Query $query
      * @return Solarium_Client_Request
      */
@@ -469,7 +473,7 @@ class Solarium_Client extends Solarium_Configurable
      * Example usage:
      * <code>
      * $client = new Solarium_Client;
-     * $query = new Solarium_Query_Ping;
+     * $query = $client->createPing();
      * $result = $client->ping($query);
      * </code>
      *
@@ -479,7 +483,7 @@ class Solarium_Client extends Solarium_Configurable
      *  execute method, thus allowing for an easy to use and clean API.
      *
      * @param Solarium_Query_Ping $query
-     * @return boolean
+     * @return Solarium_Result_Ping
      */
     public function ping($query)
     {
@@ -492,9 +496,9 @@ class Solarium_Client extends Solarium_Configurable
      * Example usage:
      * <code>
      * $client = new Solarium_Client;
-     * $update = new Solarium_Query_Update;
+     * $query = $client->createUpdate();
      * $update->addOptimize();
-     * $result = $client->ping($update);
+     * $result = $client->update($update);
      * </code>
      *
      * @see Solarium_Query_Update
@@ -517,8 +521,8 @@ class Solarium_Client extends Solarium_Configurable
      * Example usage:
      * <code>
      * $client = new Solarium_Client;
-     * $query = new Solarium_Query_Select;
-     * $result = $client->ping($query);
+     * $query = $client->createSelect();
+     * $result = $client->select($query);
      * </code>
      *
      * @see Solarium_Query_Select

library/Solarium/Client/Adapter/ZendHttp.php

@@ -43,8 +43,7 @@
  * configuration options. For more info see the manual at
  * {@link http://framework.zend.com/manual/en/zend.http.html}
  *
- * To use this adapter you need to have the Zend Framework in your include path,
- * autoloader or manually included.
+ * To use this adapter you need to have the Zend Framework available (autoloading)
  *
  * @package Solarium
  * @subpackage Client
@@ -173,7 +172,10 @@ class Solarium_Client_Adapter_ZendHttp extends Solarium_Client_Adapter
             $data = $response->getBody();
         }
 
-        return new Solarium_Client_Response($data, $response->getHeaders());
+        // this is used because getHeaders doesn't return the HTTP header...
+        $headers = explode("\n",$response->getHeadersAsString());
+
+        return new Solarium_Client_Response($data, $headers);
     }
 
 }
\ No newline at end of file

library/Solarium/Plugin/Abstract.php

@@ -64,22 +64,24 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
         $this->_client = $client;
         parent::__construct($options);
 
-        $this->_init();
+        $this->_initPlugin();
     }
 
     /**
-     * Secondary init function
+     * Plugin init function
      *
-     * This is an extension point for plugin implemenations
+     * This is an extension point for plugin implemenations.
+     * Will be called as soon as $this->_client and options have been set.
      *
      * @return void
      */
-    public function _init()
+    protected function _initPlugin()
     {
 
     }
 
     /**
+     * preCreateRequest hook
      *
      * @param Solarium_Query $query
      * @return void|Solarium_Client_Request
@@ -89,6 +91,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * postCreateRequest hook
+     *
      * @param Solarium_Query $query
      * @param Solarium_Client_Request $request
      * @return void
@@ -98,6 +102,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * preExecuteRequest hook
+     *
      * @param Solarium_Client_Request $request
      * @return void|Solarium_Client_Response
      */
@@ -106,6 +112,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * postExecuteRequest hook
+     *
      * @param Solarium_Client_Request $request
      * @param Solarium_Client_Response $response
      * @return void
@@ -115,6 +123,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * preCreateResult hook
+     *
      * @param Solarium_Query $query
      * @param Solarium_Client_Response $response
      * @return void|Solarium_Result
@@ -124,6 +134,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * postCreateResult hook
+     *
      * @param Solarium_Query $query
      * @param Solarium_Client_Response $response
      * @param Solarium_Result $result
@@ -134,6 +146,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * preExecute hook
+     *
      * @param Solarium_Query $query
      * @return void|Solarium_Result
      */
@@ -142,6 +156,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * postExecute hook
+     * 
      * @param Solarium_Query $query
      * @param Solarium_Result $result
      * @return void
@@ -151,6 +167,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
     
     /**
+     * preCreateQuery hook
+     *
      * @param string $query
      * @param mixed $options
      * @return void|Solarium_Query
@@ -160,6 +178,8 @@ abstract class Solarium_Plugin_Abstract extends Solarium_Configurable
     }
 
     /**
+     * postCreateQuery hook
+     * 
      * @param string $query
      * @param mixed $options
      * @param Solarium_Query

library/Solarium/Result.php

@@ -58,7 +58,7 @@ class Solarium_Result
     /**
      * Decode response data
      *
-     * This is lazy loaded, see getData()
+     * This is lazy loaded, {@link getData()}
      *
      * @var array
      */