## Class Apache_Solr_Service

Description

Starting point for the Solr API. Represents a Solr server resource and has methods for pinging, adding, deleting, committing, optimizing and searching.

Example Usage:

1. ...
2. $solr = new Apache_Solr_Service(); //or explicitly new Apache_Solr_Service('localhost', 8180, '/solr')
4. if ($solr->ping())
5. {
6. $solr->deleteByQuery('*:*'); //deletes ALL documents - be careful :)
8. $document = new Apache_Solr_Document();
9. $document->id = uniqid(); //or something else suitably unique
11. $document->title = 'Some Title';
12. $document->content = 'Some content for this wonderful document. Blah blah blah.';
14. $solr->addDocument($document); //if you're going to be adding documents in bulk using addDocuments
15. //with an array of documents is faster
17. $solr->commit(); //commit to see the deletes and the document
18. $solr->optimize(); //merges multiple segments into one
20. //and the one we all care about, search!
21. //any other common or custom parameters to the request handler can go in the
22. //optional 4th array argument.
23. $solr->search('content:blah', 0, 10, array('sort' => 'timestamp desc'));
24. }
25. ...

- todo: Investigate using other HTTP clients other than file_get_contents built-in handler. Could provide performance improvements when dealing with multiple requests by using HTTP's keep alive functionality

Located in /Service.php (line 80)

Class Constant Summary
METHOD_GET = 'GET'
METHOD_POST = 'POST'
NAMED_LIST_FLAT = 'flat'
NAMED_LIST_MAP = 'map'
PING_SERVLET = 'admin/ping'
SEARCH_SERVLET = 'select'
SOLR_VERSION = '1.2'
SOLR_WRITER = 'json'
SVN_ID = '$Id: Service.php 22 2009-11-09 22:46:54Z donovan.jimenez $'
SVN_REVISION = '$Revision: 22 $'
THREADS_SERVLET = 'admin/threads'
UPDATE_SERVLET = 'update'
Variable Summary
boolean $_collapseSingleValueArrays
boolean $_createDocuments
mixed $_defaultTimeout
resource $_getContext
string $_host
string $_namedListTreatment
mixed $_path
string $_pingUrl
mixed $_port
mixed $_postContext
string $_queryDelimiter
mixed $_queryStringDelimiter
mixed $_searchUrl
mixed $_threadsUrl
mixed $_updateUrl
boolean $_urlsInited
Method Summary
static string escape (string $value)
static string escapePhrase (string $value)
static string phrase (string $value)
Apache_Solr_Service __construct ([string $host = 'localhost'], [string $port = 8180], [string $path = '/solr/'])
Apache_Solr_Response add (string $rawPost)
Apache_Solr_Response addDocument (Apache_Solr_Document $document, [boolean $allowDups = false], [boolean $overwritePending = true], [boolean $overwriteCommitted = true])
Apache_Solr_Response addDocuments (array $documents, [boolean $allowDups = false], [boolean $overwritePending = true], [boolean $overwriteCommitted = true])
Apache_Solr_Response commit ([boolean $optimize = true], [boolean $waitFlush = true], [boolean $waitSearcher = true], [float $timeout = 3600])
Apache_Solr_Response delete (string $rawPost, [float $timeout = 3600])
Apache_Solr_Response deleteById (string $id, [boolean $fromPending = true], [boolean $fromCommitted = true], [float $timeout = 3600])
Apache_Solr_Response deleteByMultipleIds (array $ids, [boolean $fromPending = true], [boolean $fromCommitted = true], [float $timeout = 3600])
Apache_Solr_Response deleteByQuery (string $rawQuery, [boolean $fromPending = true], [boolean $fromCommitted = true], [float $timeout = 3600])
boolean getCollapseSingleValueArrays ()
boolean getCreateDocuments ()
string getHost ()
string getNamedListTreatment ()
string getPath ()
integer getPort ()
Apache_Solr_Response optimize ([boolean $waitFlush = true], [boolean $waitSearcher = true], [float $timeout = 3600])
float ping ([float $timeout = 2])
Apache_Solr_Response search (string $query, [int $offset = 0], [int $limit = 10], [array $params = array()], [ $method = self::METHOD_GET])
void setCollapseSingleValueArrays (boolean $collapseSingleValueArrays)
void setCreateDocuments (unknown_type $createDocuments)
void setHost (string $host)
void setNamedListTreatmet (string $namedListTreatment)
void setPath (string $path)
void setPort (integer $port)
void setQueryDelimiter (string $queryDelimiter)
void setQueryStringDelimiter (string $queryStringDelimiter)
Apache_Solr_Response threads ()
string _constructUrl (string $servlet, [ $params = array()])
string _documentToXmlFragment (Apache_Solr_Document $document)
void _initUrls ()
Apache_Solr_Response _sendRawGet (string $url, [float $timeout = FALSE])
Apache_Solr_Response _sendRawPost (string $url, string $rawPost, [float $timeout = FALSE], [string $contentType = 'text/xml; charset=UTF-8'])
string _stripCtrlChars (string $string)
Variables
boolean $_collapseSingleValueArrays = true (line 143)

Whether Apache_Solr_Response objects should have multivalue fields with only a single value collapsed to appear as a single value would.

- access: protected

boolean $_createDocuments = true (line 135)

Whether Apache_Solr_Response objects should create Apache_Solr_Documents in the returned parsed data

- access: protected

mixed $_defaultTimeout (line 187)

Default HTTP timeout when one is not specified (initialized to default_socket_timeout ini setting)

var float

- access: protected

resource $_getContext (line 180)

Reusable stream context resources for GET and POST operations

- access: protected

string $_host (line 127)

Server identification strings

- access: protected

string $_namedListTreatment = self::NAMED_LIST_MAP (line 151)

How NamedLists should be formatted in the output. This specifically effects facet counts. Valid values are Apache_Solr_Service::NAMED_LIST_MAP (default) or Apache_Solr_Service::NAMED_LIST_FLAT.

- access: protected

mixed $_path (line 127)

- access: protected

string $_pingUrl (line 166)

Constructed servlet full path URLs

- access: protected

mixed $_port (line 127)

- access: protected

mixed $_postContext (line 180)

- access: protected

string $_queryDelimiter = '?' (line 159)

Query delimiters. Someone might want to be able to change these (to use &amp; instead of & for example), so I've provided them.

- access: protected

mixed $_queryStringDelimiter = '&' (line 159)

- access: protected

mixed $_searchUrl (line 166)

- access: protected

mixed $_threadsUrl (line 166)

- access: protected

mixed $_updateUrl (line 166)

- access: protected

boolean $_urlsInited = false (line 173)

Keep track of whether our URLs have been constructed

- access: protected

Methods
static escape (line 197)

Escape a value for special query characters such as ':', '(', ')', '*', '?', etc.

NOTE: inside a phrase fewer characters need escaped, use Apache_Solr_Service::escapePhrase() instead

- access: public

static string escape (string $value)

- string $value

static escapePhrase (line 212)

Escape a value meant to be contained in a phrase for special query characters

- access: public

static string escapePhrase (string $value)

- string $value

static phrase (line 226)

Convenience function for creating phrase syntax from a value

- access: public

static string phrase (string $value)

- string $value

Constructor __construct (line 239)

Constructor. All parameters are optional and will take on default values if not specified.

- access: public

Apache_Solr_Service __construct ([string $host = 'localhost'], [string $port = 8180], [string $path = '/solr/'])

- string $host
- string $port
- string $path

add (line 650)

Raw Add Method. Takes a raw post body and sends it to the update service. Post body should be a complete and well formed "add" xml document.

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response add (string $rawPost)

- string $rawPost

addDocument (line 666)

Add a Solr Document to the index

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response addDocument (Apache_Solr_Document $document, [boolean $allowDups = false], [boolean $overwritePending = true], [boolean $overwriteCommitted = true])

- Apache_Solr_Document $document
- boolean $allowDups
- boolean $overwritePending
- boolean $overwriteCommitted

addDocuments (line 690)

Add an array of Solr Documents to the index all at once

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response addDocuments (array $documents, [boolean $allowDups = false], [boolean $overwritePending = true], [boolean $overwriteCommitted = true])

- array $documents: Should be an array of Apache_Solr_Document instances
- boolean $allowDups
- boolean $overwritePending
- boolean $overwriteCommitted

commit (line 796)

Send a commit command. Will be synchronous unless both wait parameters are set to false.

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response commit ([boolean $optimize = true], [boolean $waitFlush = true], [boolean $waitSearcher = true], [float $timeout = 3600])

- boolean $optimize: Defaults to true
- boolean $waitFlush: Defaults to true
- boolean $waitSearcher: Defaults to true
- float $timeout: Maximum expected duration (in seconds) of the commit operation on the server (otherwise, will throw a communication exception). Defaults to 1 hour

delete (line 817)

Raw Delete Method. Takes a raw post body and sends it to the update service. Body should be a complete and well formed "delete" xml document

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response delete (string $rawPost, [float $timeout = 3600])

- string $rawPost: Expected to be utf-8 encoded xml document
- float $timeout: Maximum expected duration of the delete operation on the server (otherwise, will throw a communication exception)

deleteById (line 833)

Create a delete document based on document ID

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response deleteById (string $id, [boolean $fromPending = true], [boolean $fromCommitted = true], [float $timeout = 3600])

- string $id: Expected to be utf-8 encoded
- boolean $fromPending
- boolean $fromCommitted
- float $timeout: Maximum expected duration of the delete operation on the server (otherwise, will throw a communication exception)

deleteByMultipleIds (line 857)

Create and post a delete document based on multiple document IDs.

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response deleteByMultipleIds (array $ids, [boolean $fromPending = true], [boolean $fromCommitted = true], [float $timeout = 3600])

- array $ids: Expected to be utf-8 encoded strings
- boolean $fromPending
- boolean $fromCommitted
- float $timeout: Maximum expected duration of the delete operation on the server (otherwise, will throw a communication exception)

deleteByQuery (line 888)

Create a delete document based on a query and submit it

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response deleteByQuery (string $rawQuery, [boolean $fromPending = true], [boolean $fromCommitted = true], [float $timeout = 3600])

- string $rawQuery: Expected to be utf-8 encoded
- boolean $fromPending
- boolean $fromCommitted
- float $timeout: Maximum expected duration of the delete operation on the server (otherwise, will throw a communication exception)

getCollapseSingleValueArrays (line 522)

Get the current state of the collapse single value arrays flag.

- access: public

boolean getCollapseSingleValueArrays ()
getCreateDocuments (line 502)

Get the current state of teh create documents flag.

- access: public

boolean getCreateDocuments ()
getHost (line 396)

Returns the set host

- access: public

string getHost ()
getNamedListTreatment (line 556)

Get the current setting for named list treatment.

- access: public

string getNamedListTreatment ()
getPath (line 464)

Get the set path.

- access: public

string getPath ()
getPort (line 429)

Get the set port

- access: public

integer getPort ()
optimize (line 912)

Send an optimize command. Will be synchronous unless both wait parameters are set to false.

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response optimize ([boolean $waitFlush = true], [boolean $waitSearcher = true], [float $timeout = 3600])

- boolean $waitFlush
- boolean $waitSearcher
- float $timeout: Maximum expected duration of the commit operation on the server (otherwise, will throw a communication exception)

ping (line 591)

Call the /admin/ping servlet, can be used to quickly tell if a connection to the server is able to be made.

- return: Actual time taken to ping the server, FALSE if timeout or HTTP error status occurs
- access: public

float ping ([float $timeout = 2])

- float $timeout: maximum time to wait for ping in seconds, -1 for unlimited (default is 2)

search (line 933)

Simple Search interface

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response search (string $query, [int $offset = 0], [int $limit = 10], [array $params = array()], [ $method = self::METHOD_GET])

- string $query: The raw query string
- int $offset: The starting offset for result documents
- int $limit: The maximum number of result documents to return
- array $params: key / value pairs for other query parameters (see Solr documentation), use arrays for parameter keys used more than once (e.g. facet.field)
- $method

setCollapseSingleValueArrays (line 512)

Set the collapse single value arrays flag.

- access: public

void setCollapseSingleValueArrays (boolean $collapseSingleValueArrays)

- boolean $collapseSingleValueArrays

setCreateDocuments (line 492)

Set the create documents flag. This determines whether Apache_Solr_Response objects will parse the response and create Apache_Solr_Document instances in place.

- access: public

void setCreateDocuments (unknown_type $createDocuments)

- unknown_type $createDocuments

setHost (line 406)

Set the host used. If empty will fallback to constants

- access: public

void setHost (string $host)

- string $host

setNamedListTreatmet (line 534)

Set how NamedLists should be formatted in the response data. This mainly effects the facet counts format.

- throws: Exception If invalid option is set
- access: public

void setNamedListTreatmet (string $namedListTreatment)

- string $namedListTreatment

setPath (line 474)

Set the path used. If empty will fallback to constants

- access: public

void setPath (string $path)

- string $path

setPort (line 439)

Set the port used. If empty will fallback to constants

- access: public

void setPort (integer $port)

- integer $port

setQueryDelimiter (line 568)

Set the string used to separate the path form the query string.

Defaulted to '?'

- access: public

void setQueryDelimiter (string $queryDelimiter)

- string $queryDelimiter

setQueryStringDelimiter (line 579)

Set the string used to separate the parameters in thequery string Defaulted to '&'

- access: public

void setQueryStringDelimiter (string $queryStringDelimiter)

- string $queryStringDelimiter

threads (line 636)

Call the /admin/threads servlet and retrieve information about all threads in the Solr servlet's thread group. Useful for diagnostics.

- throws: Exception If an error occurs during the service call
- access: public

Apache_Solr_Response threads ()
_constructUrl (line 267)

Return a valid http URL given this server's host, port and path and a provided servlet name

- access: protected

string _constructUrl (string $servlet, [ $params = array()])

- string $servlet
- $params

_documentToXmlFragment (line 716)

Create an XML fragment from a Apache_Solr_Document instance appropriate for use inside a Solr add call

- access: protected

string _documentToXmlFragment (Apache_Solr_Document $document)

- Apache_Solr_Document $document

_initUrls (line 292)

Construct the Full URLs for the three servlets we reference

- access: protected

void _initUrls ()
_sendRawGet (line 312)

Central method for making a get operation against this Solr Server

- throws: Exception If a non 200 response status is returned
- access: protected

Apache_Solr_Response _sendRawGet (string $url, [float $timeout = FALSE])

- string $url
- float $timeout: Read timeout in seconds

_sendRawPost (line 351)

Central method for making a post operation against this Solr Server

- throws: Exception If a non 200 response status is returned
- access: protected

Apache_Solr_Response _sendRawPost (string $url, string $rawPost, [float $timeout = FALSE], [string $contentType = 'text/xml; charset=UTF-8'])

- string $url
- string $rawPost
- float $timeout: Read timeout in seconds
- string $contentType

_stripCtrlChars (line 778)

Replace control (non-printable) characters from string that are invalid to Solr's XML parser with a space.

- access: protected

string _stripCtrlChars (string $string)

- string $string

Class Constants
METHOD_GET = 'GET' (line 111)

Search HTTP Methods

METHOD_POST = 'POST' (line 112)
NAMED_LIST_FLAT = 'flat' (line 105)

NamedList Treatment constants

NAMED_LIST_MAP = 'map' (line 106)
PING_SERVLET = 'admin/ping' (line 117)

Servlet mappings

SEARCH_SERVLET = 'select' (line 119)
SOLR_VERSION = '1.2' (line 95)

Response version we support

SOLR_WRITER = 'json' (line 100)

Response writer we'll request - JSON. See http://code.google.com/p/solr-php-client/issues/detail?id=6#c1 for reasoning

SVN_ID = '$Id: Service.php 22 2009-11-09 22:46:54Z donovan.jimenez $' (line 90)

SVN ID meta data for this class

SVN_REVISION = '$Revision: 22 $' (line 85)

SVN Revision meta data for this class

THREADS_SERVLET = 'admin/threads' (line 120)
UPDATE_SERVLET = 'update' (line 118)

Documentation generated on Mon, 09 Nov 2009 18:15:45 -0500 by phpDocumentor 1.4.2