## 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 86)

Class Constant Summary
EXTRACT_SERVLET = 'update/extract'
METHOD_GET = 'GET'
METHOD_POST = 'POST'
NAMED_LIST_FLAT = 'flat'
NAMED_LIST_MAP = 'map'
PING_SERVLET = 'admin/ping'
SEARCH_SERVLET = 'select'
SOLR_WRITER = 'json'
SVN_ID = '$Id: Service.php 59 2011-02-08 20:38:59Z donovan.jimenez $'
SVN_REVISION = '$Revision: 59 $'
THREADS_SERVLET = 'admin/threads'
UPDATE_SERVLET = 'update'
Variable Summary
boolean $_collapseSingleValueArrays
boolean $_createDocuments
string $_host
Apache_Solr_HttpTransport_Interface $_httpTransport
string $_namedListTreatment
mixed $_path
string $_pingUrl
mixed $_port
mixed $_queryBracketsEscaped
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_Response add (string $rawPost)
Apache_Solr_Response addDocument (Apache_Solr_Document $document, [boolean $allowDups = false], [boolean $overwritePending = true], [boolean $overwriteCommitted = true], [integer $commitWithin = 0])
Apache_Solr_Response addDocuments (array $documents, [boolean $allowDups = false], [boolean $overwritePending = true], [boolean $overwriteCommitted = true], [integer $commitWithin = 0])
Apache_Solr_Response commit ([boolean $expungeDeletes = false], [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])
Apache_Solr_Response extract (string $file, [array $params = array()], [Apache_Solr_Document $document = null], [string $mimetype = 'application/octet-stream'])
Apache_Solr_Response extractFromString (string $data, [array $params = array()], [Apache_Solr_Document $document = null], [string $mimetype = 'application/octet-stream'])
Apache_Solr_Response extractFromUrl (string $url, [array $params = array()], [Apache_Solr_Document $document = null], [string $mimetype = 'application/octet-stream'])
boolean getCollapseSingleValueArrays ()
boolean getCreateDocuments ()
float getDefaultTimeout ()
string getHost ()
HttpTransportInterface getHttpTransport ()
string getNamedListTreatment ()
string getPath ()
integer getPort ()
Apache_Solr_Service __construct ([string $host = 'localhost'], [string $port = 8180], [string $path = '/solr/'], [Apache_Solr_HttpTransport_Interface $httpTransport = false])
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()], [string $method = self::METHOD_GET])
void setCollapseSingleValueArrays (boolean $collapseSingleValueArrays)
void setCreateDocuments (boolean $createDocuments)
void setDefaultTimeout (float $timeout)
void setHost (string $host)
void setHttpTransport (Apache_Solr_HttpTransport_Interface $httpTransport)
void setNamedListTreatment (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 _generateQueryString ( $params)
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 145)

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 137)

Whether Apache_Solr_Response objects should create Apache_Solr_Documents in the returned parsed data

- access: protected

string $_host (line 129)

Server identification strings

- access: protected

Apache_Solr_HttpTransport_Interface $_httpTransport = false (line 182)

HTTP Transport implementation (pluggable)

- access: protected

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

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 129)

- access: protected

string $_pingUrl (line 168)

Constructed servlet full path URLs

- access: protected

mixed $_port (line 129)

- access: protected

mixed $_queryBracketsEscaped = true (line 161)

- access: protected

string $_queryDelimiter = '?' (line 161)

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 161)

- access: protected

mixed $_searchUrl (line 168)

- access: protected

mixed $_threadsUrl (line 168)

- access: protected

mixed $_updateUrl (line 168)

- access: protected

boolean $_urlsInited = false (line 175)

Keep track of whether our URLs have been constructed

- access: protected

Methods
static escape (line 192)

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 207)

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 221)

Convenience function for creating phrase syntax from a value

- access: public

static string phrase (string $value)

- string $value

add (line 667)

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: Apache_Solr_HttpTransportException If an error occurs during the service call
- access: public

Apache_Solr_Response add (string $rawPost)

- string $rawPost

addDocument (line 684)

Add a Solr Document to the index

- throws: Apache_Solr_HttpTransportException 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], [integer $commitWithin = 0])

- Apache_Solr_Document $document
- boolean $allowDups
- boolean $overwritePending
- boolean $overwriteCommitted
- integer $commitWithin: The number of milliseconds that a document must be committed within, see @{link http://wiki.apache.org/solr/UpdateXmlMessages#The_Update_Schema} for details. If left empty this property will not be set in the request.

addDocuments (line 712)

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

- throws: Apache_Solr_HttpTransportException 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], [integer $commitWithin = 0])

- array $documents: Should be an array of Apache_Solr_Document instances
- boolean $allowDups
- boolean $overwritePending
- boolean $overwriteCommitted
- integer $commitWithin: The number of milliseconds that a document must be committed within, see @{link http://wiki.apache.org/solr/UpdateXmlMessages#The_Update_Schema} for details. If left empty this property will not be set in the request.

commit (line 821)

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

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

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

- boolean $expungeDeletes: Defaults to false, merge segments with deletes away
- boolean $waitFlush: Defaults to true, block until index changes are flushed to disk
- boolean $waitSearcher: Defaults to true, block until a new searcher is opened and registered as the main query searcher, making the changes visible
- 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 842)

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: Apache_Solr_HttpTransportException 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 858)

Create a delete document based on document ID

- throws: Apache_Solr_HttpTransportException 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 882)

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

- throws: Apache_Solr_HttpTransportException 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 913)

Create a delete document based on a query and submit it

- throws: Apache_Solr_HttpTransportException 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)

extract (line 944)

Use Solr Cell to extract document contents. See http://wiki.apache.org/solr/ExtractingRequestHandler for information on how to use Solr Cell and what parameters are available.

NOTE: when passing an Apache_Solr_Document instance, field names and boosts will automatically be prepended by "literal." and "boost." as appropriate. Any keys from the $params array will NOT be treated this way. Any mappings from the document will overwrite key / value pairs in the params array if they have the same name (e.g. you pass a "literal.id" key and value in your $params array but you also pass in a document isntance with an "id" field" - the document's value(s) will take precedence).

- throws: Apache_Solr_InvalidArgumentException if $file, $params, or $document are invalid.
- access: public

Apache_Solr_Response extract (string $file, [array $params = array()], [Apache_Solr_Document $document = null], [string $mimetype = 'application/octet-stream'])

- string $file: Path to file to extract data from
- array $params: optional array of key value pairs that will be sent with the post (see Solr Cell documentation)
- Apache_Solr_Document $document: optional document that will be used to generate post parameters (literal.* and boost.* params)
- string $mimetype: optional mimetype specification (for the file being extracted)

extractFromString (line 1005)

Use Solr Cell to extract document contents. See http://wiki.apache.org/solr/ExtractingRequestHandler for information on how to use Solr Cell and what parameters are available.

NOTE: when passing an Apache_Solr_Document instance, field names and boosts will automatically be prepended by "literal." and "boost." as appropriate. Any keys from the $params array will NOT be treated this way. Any mappings from the document will overwrite key / value pairs in the params array if they have the same name (e.g. you pass a "literal.id" key and value in your $params array but you also pass in a document isntance with an "id" field" - the document's value(s) will take precedence).

- todo: Should be using multipart/form-data to post parameter values, but I could not get my implementation to work. Needs revisisted.
- throws: Apache_Solr_InvalidArgumentException if $file, $params, or $document are invalid.
- access: public

Apache_Solr_Response extractFromString (string $data, [array $params = array()], [Apache_Solr_Document $document = null], [string $mimetype = 'application/octet-stream'])

- string $data: Data that will be passed to Solr Cell
- array $params: optional array of key value pairs that will be sent with the post (see Solr Cell documentation)
- Apache_Solr_Document $document: optional document that will be used to generate post parameters (literal.* and boost.* params)
- string $mimetype: optional mimetype specification (for the file being extracted)

extractFromUrl (line 1068)

Use Solr Cell to extract document contents. See http://wiki.apache.org/solr/ExtractingRequestHandler for information on how to use Solr Cell and what parameters are available.

NOTE: when passing an Apache_Solr_Document instance, field names and boosts will automatically be prepended by "literal." and "boost." as appropriate. Any keys from the $params array will NOT be treated this way. Any mappings from the document will overwrite key / value pairs in the params array if they have the same name (e.g. you pass a "literal.id" key and value in your $params array but you also pass in a document isntance with an "id" field" - the document's value(s) will take precedence).

- throws: Apache_Solr_InvalidArgumentException if $url, $params, or $document are invalid.
- access: public

Apache_Solr_Response extractFromUrl (string $url, [array $params = array()], [Apache_Solr_Document $document = null], [string $mimetype = 'application/octet-stream'])

- string $url: URL
- array $params: optional array of key value pairs that will be sent with the post (see Solr Cell documentation)
- Apache_Solr_Document $document: optional document that will be used to generate post parameters (literal.* and boost.* params)
- string $mimetype: optional mimetype specification (for the file being extracted)

getCollapseSingleValueArrays (line 533)

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

- access: public

boolean getCollapseSingleValueArrays ()
getCreateDocuments (line 513)

Get the current state of teh create documents flag.

- access: public

boolean getCreateDocuments ()
getDefaultTimeout (line 546)

Get the current default timeout setting (initially the default_socket_timeout ini setting) in seconds

- deprecated: Use the getDefaultTimeout method on the HTTP transport implementation
- access: public

float getDefaultTimeout ()
getHost (line 375)

Returns the set host

- access: public

string getHost ()
getHttpTransport (line 474)

Get the current configured HTTP Transport

- access: public

HttpTransportInterface getHttpTransport ()
getNamedListTreatment (line 592)

Get the current setting for named list treatment.

- access: public

string getNamedListTreatment ()
getPath (line 447)

Get the set path.

- access: public

string getPath ()
getPort (line 410)

Get the set port

- access: public

integer getPort ()
Constructor __construct (line 235)

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/'], [Apache_Solr_HttpTransport_Interface $httpTransport = false])

- string $host
- string $port
- string $path
- Apache_Solr_HttpTransport_Interface $httpTransport

optimize (line 1117)

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

- throws: Apache_Solr_HttpTransportException 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 626)

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 1140)

Simple Search interface

- throws: Apache_Solr_InvalidArgumentException If an invalid HTTP method is used
- throws: Apache_Solr_HttpTransportException 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()], [string $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)
- string $method: The HTTP method (Apache_Solr_Service::METHOD_GET or Apache_Solr_Service::METHOD::POST)

setCollapseSingleValueArrays (line 523)

Set the collapse single value arrays flag.

- access: public

void setCollapseSingleValueArrays (boolean $collapseSingleValueArrays)

- boolean $collapseSingleValueArrays

setCreateDocuments (line 503)

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 (boolean $createDocuments)

- boolean $createDocuments

setDefaultTimeout (line 558)

Set the default timeout for all calls that aren't passed a specific timeout

- deprecated: Use the setDefaultTimeout method on the HTTP transport implementation
- access: public

void setDefaultTimeout (float $timeout)

- float $timeout: Timeout value in seconds

setHost (line 387)

Set the host used. If empty will fallback to constants

- throws: Apache_Solr_InvalidArgumentException If the host parameter is empty
- access: public

void setHost (string $host)

- string $host

setHttpTransport (line 492)

Set the HTTP Transport implemenation that will be used for all HTTP requests

- access: public

void setHttpTransport (Apache_Solr_HttpTransport_Interface $httpTransport)

- Apache_Solr_HttpTransport_Interface $httpTransport

setNamedListTreatment (line 570)

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

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

void setNamedListTreatment (string $namedListTreatment)

- string $namedListTreatment

setPath (line 457)

Set the path used. If empty will fallback to constants

- access: public

void setPath (string $path)

- string $path

setPort (line 422)

Set the port used. If empty will fallback to constants

- throws: Apache_Solr_InvalidArgumentException If the port parameter is empty
- access: public

void setPort (integer $port)

- integer $port

setQueryDelimiter (line 603)

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

Defaulted to '?'

- access: public

void setQueryDelimiter (string $queryDelimiter)

- string $queryDelimiter

setQueryStringDelimiter (line 614)

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

- access: public

void setQueryStringDelimiter (string $queryStringDelimiter)

- string $queryStringDelimiter

threads (line 653)

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

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

Apache_Solr_Response threads ()
_constructUrl (line 258)

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 741)

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

_generateQueryString (line 295)

- access: protected

void _generateQueryString ( $params)

- $params

_initUrls (line 283)

Construct the Full URLs for the three servlets we reference

- access: protected

void _initUrls ()
_sendRawGet (line 329)

Central method for making a get operation against this Solr Server

- throws: Apache_Solr_HttpTransportException 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 355)

Central method for making a post operation against this Solr Server

- throws: Apache_Solr_HttpTransportException 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 803)

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
EXTRACT_SERVLET = 'update/extract' (line 122)
METHOD_GET = 'GET' (line 112)

Search HTTP Methods

METHOD_POST = 'POST' (line 113)
NAMED_LIST_FLAT = 'flat' (line 106)

NamedList Treatment constants

NAMED_LIST_MAP = 'map' (line 107)
PING_SERVLET = 'admin/ping' (line 118)

Servlet mappings

SEARCH_SERVLET = 'select' (line 120)
SOLR_WRITER = 'json' (line 101)

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 59 2011-02-08 20:38:59Z donovan.jimenez $' (line 96)

SVN ID meta data for this class

SVN_REVISION = '$Revision: 59 $' (line 91)

SVN Revision meta data for this class

THREADS_SERVLET = 'admin/threads' (line 121)
UPDATE_SERVLET = 'update' (line 119)

Documentation generated on Wed, 04 May 2011 11:01:19 -0400 by phpDocumentor 1.4.3