Skip to content

S
solarium
Commit f14c2fcc authored by Bas de Nooijer's avatar Bas de Nooijer
Browse files
Options

- many phpdoc improvements

parent 0c731d60
Show whitespace changes
Inline Side-by-side
Showing with 270 additions and 32 deletions
library/Solarium/Client/Adapter.php
View file @ f14c2fcc
......@@ -37,6 +37,22 @@
/**
* Base class for all adapters
*
* The goal of an adapter is to accept a query, execute it and return the right
* result object. This is actually quite a complex task as it involves the
* handling of all Solr communication.
*
* The adapter structure allows for varying implementations of this task.
*
* Most adapters will use some sort of HTTP client. In that case the
* Solarium_Client_Request request builders and Solarium_Client_Response
* response parsers can be used to simplify HTTP communication.
* See {@link Solarium_Client_Adapter_Http} as an example.
*
* However an adapter may also implement all logic by itself if needed.
*
* @package Solarium
* @subpackage Client
*/
abstract class Solarium_Client_Adapter extends Solarium_Configurable
{
......@@ -53,7 +69,9 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
);
/**
* Set options (overrides any existing values)
* Set options
*
* Overrides any existing values
*
* @param array $options
* @return void
......@@ -64,6 +82,8 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
}
/**
* Execute a select query
*
* Abstract method to require an implementation inside all adapters.
* If the adapter cannot support this method it should implement a method
* that throws an exception.
......@@ -75,6 +95,8 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
abstract public function select($query);
/**
* Execute a ping query
*
* Abstract method to require an implementation inside all adapters.
* If the adapter cannot support this method it should implement a method
* that throws an exception.
......@@ -86,6 +108,8 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
abstract public function ping($query);
/**
* Execute an update query
*
* Abstract method to require an implementation inside all adapters.
* If the adapter cannot support this method it should implement a method
* that throws an exception.
......
library/Solarium/Client/Adapter/Http.php
View file @ f14c2fcc
......@@ -36,7 +36,10 @@
*/
/**
* A very basic adapter using file_get_contents for retrieving data from Solr
* Basic HTTP adapter using a stream
*
* @package Solarium
* @subpackage Client
*/
class Solarium_Client_Adapter_Http extends Solarium_Client_Adapter
{
......@@ -96,7 +99,6 @@ class Solarium_Client_Adapter_Http extends Solarium_Client_Adapter
/**
* Handle Solr communication
*
* @todo implement timeout
* @todo check http response code
*
* @throws Solarium_Exception
......@@ -146,13 +148,12 @@ class Solarium_Client_Adapter_Http extends Solarium_Client_Adapter
}
}
/**
* TODO
* Decode json response data
*
* @throws Solarium_Exception
* @param $data
* @return mixed
* @param string $data
* @return string
*/
protected function _jsonDecode($data)
{
......
library/Solarium/Client/Adapter/ZendHttp.php
View file @ f14c2fcc
......@@ -36,7 +36,7 @@
*/
/**
* An adapter that uses a Zend_Http_Client for Solr request
* Adapter that uses a Zend_Http_Client
*
* The Zend Framework HTTP client has many great features and has lots of
* configuration options. For more info see the manual at
......@@ -56,7 +56,9 @@ class Solarium_Client_Adapter_ZendHttp extends Solarium_Client_Adapter_Http
protected $_zendHttp;
/**
* Set options (overrides any existing values)
* Set options
*
* Overrides any existing values.
*
* If the options array has an 'adapteroptions' entry it is forwarded to the
* Zend_Http_Client. See the Zend_Http_Clientdocs for the many config
......
library/Solarium/Client/Request.php
View file @ f14c2fcc
......@@ -36,7 +36,16 @@
*/
/**
* Base class for building Solr HTTP requests
*
* Most {@link Solarium_Client_Adapter} implementations will use HTTP for
* communicating with Solr. While the HTTP part is adapter-specific, generating
* the HTTP request setting (url, postdata, etc.) is not.
* This abstract class is the base for several requestbuilders that generate the
* settings for the various querytypes.
*
* @package Solarium
* @subpackage Client
*/
abstract class Solarium_Client_Request
{
......@@ -48,30 +57,37 @@ abstract class Solarium_Client_Request
const HEAD = 'HEAD';
/**
* TODO
* Query instance
*
* The query that has to be used for building the request.
*
* @var Solarium_Query
*/
protected $_query;
/**
* TODO
* Adapter options
*
* When the adapter class the {@link __construct()} method it forwards it's
* options. These options are needed for building the right uri.
*
* @var array
*/
protected $_options;
/**
* TODO
* HTTP GET params
*
* Used for building the uri in {@link buildUri()}
*
* @var array
*/
protected $_params;
/**
* TODO
* Constructor
*
* @param array|object $options
* @param array|object $options Passed on by the adapter
* @param Solarium_Query $query
*/
public function __construct($options, $query)
......@@ -81,7 +97,7 @@ abstract class Solarium_Client_Request
}
/**
* TODO
* Get HTTP request method
*
* @return string
*/
......@@ -91,15 +107,21 @@ abstract class Solarium_Client_Request
}
/**
* TODO
* Get request uri
*
* To be implemented by query specific request builders.
*
* @abstract
* @return void
* @return string
*/
abstract public function getUri();
/**
* TODO
* Get raw POST data
*
* Returns null by default, disabling raw POST.
* If raw POST data is needed for a request the builder must override this
* method and return a data string. This string must be safely encoded.
*
* @return null
*/
......@@ -109,7 +131,7 @@ abstract class Solarium_Client_Request
}
/**
* TODO
* Get request GET params
*
* @return array
*/
......@@ -121,6 +143,12 @@ abstract class Solarium_Client_Request
/**
* Build a URL for this request
*
* Based on {@link $_options} and {@link $_params} as input.
*
* {@internal} Solr expects multiple GET params of the same name instead of
* the PHP array type notation. Therefore the result of http_build_query
* has to be altered.
*
* @return string
*/
public function buildUri()
......@@ -150,6 +178,8 @@ abstract class Solarium_Client_Request
/**
* Render a boolean attribute
*
* For use in building XML messages
*
* @param string $name
* @param boolean $value
* @return string
......@@ -167,6 +197,8 @@ abstract class Solarium_Client_Request
/**
* Render an attribute
*
* For use in building XML messages
*
* @param string $name
* @param striung $value
* @return string
......@@ -183,6 +215,9 @@ abstract class Solarium_Client_Request
/**
* Render a param with localParams
*
* LocalParams can be use in various Solr GET params.
* {@link http://wiki.apache.org/solr/LocalParams}
*
* @param string $value
* @param array $localParams in key => value format
* @return string with Solr localparams syntax
......@@ -207,7 +242,20 @@ abstract class Solarium_Client_Request
return $value;
}
/**
* Add a param to the request
*
* This method makes adding params easy in two ways:
* - empty params are filtered out, so you don't to manually check each
* param
* - if you add the same param twice it will be converted into a multivalue
* param automatically. This way you don't need to check for single or
* multiple values beforehand.
*
* @param string $name
* @param string $value
* @return void
*/
public function addParam($name, $value)
{
if (0 === strlen($value)) return;
......
library/Solarium/Client/Request/Ping.php
View file @ f14c2fcc
......@@ -36,16 +36,34 @@
*/
/**
* Builds ping request, for use in adapters.
* Build a ping request
*
* @package Solarium
* @subpackage Client
*/
class Solarium_Client_Request_Ping extends Solarium_Client_Request
{
/**
* Get uri
*
* Uses the default {@link buildUri()} method, no special uri needed in this
* case.
*
* @return string
*/
public function getUri()
{
return $this->buildUri();
}
/**
* Get HTTP request method
*
* Ping has no useful result data, so a more optimal HEAD request is used.
*
* @return string
*/
public function getMethod()
{
return self::HEAD;
......
library/Solarium/Client/Request/Select.php
View file @ f14c2fcc
......@@ -36,11 +36,22 @@
*/
/**
* Builds select request, for use in adapters.
* Build a select request
*
* @package Solarium
* @subpackage Client
*/
class Solarium_Client_Request_Select extends Solarium_Client_Request
{
/**
* Get uri
*
* Builds a complex uri based on the query settings
*
* @throws Solarium_Exception
* @return string
*/
public function getUri()
{
$this->_params = array(
......@@ -94,6 +105,12 @@ class Solarium_Client_Request_Select extends Solarium_Client_Request
return $this->buildUri();
}
/**
* Add params for a field facet to request
*
* @param mixed $facet
* @return void
*/
public function addFacetField($facet)
{
$field = $facet->getField();
......@@ -115,6 +132,12 @@ class Solarium_Client_Request_Select extends Solarium_Client_Request
$this->addParam("f.$field.facet.method", $facet->getMethod());
}
/**
* Add params for a field query to request
*
* @param mixed $facet
* @return void
*/
public function addFacetQuery($facet)
{
$this->addParam(
......
library/Solarium/Client/Request/Update.php
View file @ f14c2fcc
......@@ -36,13 +36,18 @@
*/
/**
* Builds XML messages from update queries, for use in adapters.
* Build an update request
*
* @package Solarium
* @subpackage Client
*/
class Solarium_Client_Request_Update extends Solarium_Client_Request
{
/**
* TODO
* Get HTTP request method
*
* Update uses raw POST data so a POST method has to be used.
*
* @return string
*/
......@@ -52,7 +57,11 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
}
/**
* TODO
* Get uri
*
* Return the default url with the addition of the wt param.
* This enables a JSON response, that is the easiest and most efficient
* format to decode in the response handler.
*
* @return string
*/
......@@ -63,7 +72,9 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
}
/**
* TODO
* Generates raw POST data
*
* Each commandtype is delegated to a separate builder method.
*
* @throws Solarium_Exception
* @return string
......@@ -99,6 +110,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
}
/**
* Build XML for an add command
*
* @param Solarium_Query_Update_Command_Add $command
* @return string
*/
......@@ -130,6 +143,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
}
/**
* Build XML for a delete command
*
* @param Solarium_Query_Update_Command_Delete $command
* @return string
*/
......@@ -150,6 +165,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
}
/**
* Build XML for an update command
*
* @param Solarium_Query_Update_Command_Optimize $command
* @return string
*/
......@@ -165,6 +182,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
}
/**
* Build XML for a commit command
*
* @param Solarium_Query_Update_Command_Commit $command
* @return string
*/
......@@ -183,6 +202,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
}
/**
* Build XMl for a rollback command
*
* @return string
*/
public function buildRollbackXml()
......
library/Solarium/Client/Response.php
View file @ f14c2fcc
......@@ -36,21 +36,63 @@
*/
/**
* Handles Solr response, for use in adapters.
* Base class for handling Solr HTTP responses
*
* Most {@link Solarium_Client_Adapter} implementations will use HTTP for
* communicating with Solr. While the HTTP part is adapter-specific, the parsing
* of the response into Solarium_Result classes is not. This abstract class is
* the base for several response handlers that do just that for the various
* querytypes.
*
* @package Solarium
* @subpackage Client
*/
abstract class Solarium_Client_Response
{
/**
* Query instance
*
* The query that was used for executing a request that led to this
* response. The query holds important settings for generating the right
* result, like the resultclass and documentclass settings.
*
* @var Solarium_Query
*/
protected $_query;
/**
* Response data
*
* A (json)decoded HTTP response body data array.
*
* @var array
*/
protected $_data;
/**
* Constructor
*
* @param Solarium_Query $query Query instance that was used for the request
* @param array $data Decoded data array of the HTTP response
*/
public function __construct($query, $data = null)
{
$this->_query = $query;
$this->_data = $data;
}
/**
* Get a Solarium_Result instance for the response
*
* When this method is called the actual response parsing is started.
*
* @internal Must be implemented in descendents because this parsing is
* query specific.
*
* @abstract
* @return mixed
*/
abstract function getResult();
}
\ No newline at end of file
library/Solarium/Client/Response/Select.php
View file @ f14c2fcc
......@@ -36,14 +36,36 @@
*/
/**
* Handles Solr select response, for use in adapters.
* Parse select response data
*
* Will create a result object based on response data of the type
* {@Solarium_Result_Select} (or your own resultclass setting)
*
* @package Solarium
* @subpackage Client
*/
class Solarium_Client_Response_Select extends Solarium_Client_Response
{
/**
* Facet results
*
* Filled by the _addFacet* methods (for instance {@_addFacetField()})
*
* @var array
*/
protected $_facets = array();
/**
* Get a result instance for the response
*
* When this method is called the actual response parsing is done.
*
* @return mixed
*/
public function getResult()
{
// create document instances
$documentClass = $this->_query->getOption('documentclass');
$documents = array();
if (isset($this->_data['response']['docs'])) {
......@@ -53,6 +75,7 @@ class Solarium_Client_Response_Select extends Solarium_Client_Response
}
}
// create facet results
foreach ($this->_query->getFacets() AS $facet) {
switch ($facet->getType()) {
case Solarium_Query_Select_Facet::FIELD:
......@@ -66,16 +89,24 @@ class Solarium_Client_Response_Select extends Solarium_Client_Response
}
}
// add general data
$status = $this->_data['responseHeader']['status'];
$queryTime = $this->_data['responseHeader']['QTime'];
$numFound = $this->_data['response']['numFound'];
// create the result instance that combines all data
$resultClass = $this->_query->getOption('resultclass');
return new $resultClass(
$status, $queryTime, $numFound, $documents, $this->_facets
);
}
/**
* Add a facet result for a field facet
*
* @param mixed $facet
* @return void
*/
protected function _addFacetField($facet)
{
$key = $facet->getKey();
......@@ -96,6 +127,12 @@ class Solarium_Client_Response_Select extends Solarium_Client_Response
}
}
/**
* Add a facet result for a field query
*
* @param mixed $facet
* @return void
*/
protected function _addFacetQuery($facet)
{
$key = $facet->getKey();
......
library/Solarium/Client/Response/Update.php
View file @ f14c2fcc
......@@ -36,11 +36,24 @@
*/
/**
* Handles Solr select response, for use in adapters.
* Parse update response data
*
* Will create a result object based on response data of the type
* {@Solarium_Result_Update} (or your own resultclass setting)
*
* @package Solarium
* @subpackage Client
*/
class Solarium_Client_Response_Update extends Solarium_Client_Response
{
/**
* Get a result instance for the response
*
* When this method is called the actual response parsing is done.
*
* @return mixed
*/
public function getResult()
{
$resultClass = $this->_query->getOption('resultclass');
......
tests/Solarium/Client/Request/SelectTest.php
View file @ f14c2fcc
......@@ -46,6 +46,15 @@ class Solarium_Client_Request_SelectTest extends PHPUnit_Framework_TestCase
$this->_query = new Solarium_Query_Select;
}
public function testGetMethod()
{
$request = new Solarium_Client_Request_Select($this->_options, $this->_query);
$this->assertEquals(
Solarium_Client_Request::GET,
$request->getMethod()
);
}
public function testSelectUrlWithDefaultValues()
{
$request = new Solarium_Client_Request_Select($this->_options, $this->_query);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment