<para>In this chapter the installation of Solarium is covered and a quick-start with some simple queries. If you want to get a feel for Solarium you can skip the installation part and go right to the select and update query pages. If you intend to read the rest of the manual you might skip the example queries, they will be covered in-depth in their own chapters.</para>
<sect1>
<title>Installation</title>
<important>For installing Solarium you need at least PHP version 5.2</important>
<sect2>
<title>Getting Solarium</title>
<para>There are two ways to get Solarium. You can download a prepacked release from GitHub, or use git. In this case a prepacked download is assumed.</para>
<para>Go to the Solarium GitHub project page (<ulinkurl="https://github.com/basdenooijer/solarium">https://github.com/basdenooijer/solarium</ulink>) and click 'Downloads'. Select a version and download the file. Unpack the file, the Solarium library can be found in the 'library' folder.</para>
</sect2>
<sect2>
<title>Making Solarium available in your application</title>
<para>
Solarium doesn't use any require or include statements. See <ulinkurl="http://wiki.php.net/pear/rfc/pear2_standards#use_of_includerequirerequire_onceinclude_once_not_allowed">this page</ulink> for the reasons why.
</para>
<para>
This means you need to make sure yourself the classes are available. This can be done using an autoloader, see <ulinkurl="https://gist.github.com/836745">https://gist.github.com/836745</ulink> for an example.
</para>
</sect2>
<sect2>
<title>Checking Solarium</title>
<para>To check whether your application has Solarium available you can do a version check with the following code:</para>
<example>
<title>Checking Solarium availability</title>
<programlisting><![CDATA[
echo Solarium_Version::VERSION;
]]></programlisting>
</example>
<para>If everything works you should see the version of Solarium you downloaded.</para>
</sect2>
</sect1>
<sect1>
<title>Creating a client instance</title>
<para>TODO intro / steps</para>
<example>
<title>Creating a Solarium client instance</title>
<para>A ping query can be used to check the connection to the Solr server and the health of the Solr server. It's not just a network ping, it will execute a query to check Solr health. You can set this query in the Solr config with the 'pingQuery' directive.</para>
<caution>It's not advisable to check Solr with a ping before every request, this can have a big performance import. You are better of using the ping query with intervals, or as a check after a query error to see if the query was faulty or if Solr has problems.</caution>
<sect1>
<title>Building a ping query</title>
<para>TODO</para>
</sect1>
<sect1>
<title>Executing a ping query</title>
<para>TODO</para>
</sect1>
<sect1>
<title>The result of a ping query</title>
<para>A ping query has no useful result. If you don't get an exception the ping request was succesful.</para>
<para>Solarium is a Solr client library for PHP applications.</para>
<para>The main goal of Solarium is to offer good modelling of Solr functionality. Most existing Solr clients in PHP handle just the communication with Solr. This still leaves you responsible for constructing query strings and parameters, and for handling the results.</para>
<para>
This works just fine for simple use cases, however when you for instance start using complex filterqueries and faceting with excludes it soon becomes quite complex to build your requests. Solarium aims to:
</para>
<itemizedlist>
<listitem>
<para>
Releave the developer of the "raw communication", like setting params, building complex query request strings
</para>
</listitem>
<listitem>
<para>
Allow for reuse, for instance a query can be extended to modify it
</para>
</listitem>
<listitem>
<para>
Be flexible. The query and result models are not tied to a specific Solr client implementation. Although there currently is only one Solr Client adapter this can easily be extended. All models can be extended by your own implementation if needed.
</para>
</listitem>
<listitem>
<para>
Be usable in any PHP application. No dependencies on other frameworks. Solarium tries to follow the Zend Framework standard and integrates nicely with ZF, but doesn’t in rely on it.
</para>
</listitem>
<listitem>
<para>
Accurately model Solr. For instance the updating of a Solr index. Most clients have separate add, delete and commit methods that also issue separate requests. But Solr actually has an update handler that supports all those actions in a single request. The model should reflect this while keeping it easy to use, instead of over-simplifying it.
</para>
</listitem>
<listitem>
<para>
Find a good balance between nice and feature-rich code and performance. A library/framework for general use will never be as fast as a custom implementation that only contains the bare minimum for your use case. But the performance difference between the two should be at a reasonable level. And because of the dynamic nature of PHP the models can’t be too extensive, yet they should not be over-simplified.
</para>
</listitem>
</itemizedlist>
<para>Solarium uses GitHub, the project page is <ulinkurl="https://github.com/basdenooijer/solarium">https://github.com/basdenooijer/solarium</ulink></para>
</sect2>
<sect2>
<title>Intended audience</title>
<para>This manual is written for developers. A good knowledge of PHP is assumed, and a least some basic experience with Solr. This manual will explain how to use Solr with Solarium, but won't explain all Solr functionalities. There are several good sources for more Solr info:</para>
Update queries allow you to add, delete, commit, optimize and rollback commands.
For all the details about the Solr update handler please see the Solr documentation, but some important notes:
</para>
<itemizedlist>
<listitem>
<para>
Solr has no 'update' command. But if you add a document with a value for the 'unique key' field that already exists in the index that existing document will be overwritten by your new document.
</para>
</listitem>
<listitem>
<para>
You can only add complete documents. If you want to update only a single field you still need to 'add' the whole document.
</para>
</listitem>
<listitem>
<para>
Always use a database or other persistent storage as the source for building documents to add.
Don't be tempted to emulate an update command by selecting a document, altering it and adding it.
Almost all schemas will have fields that are indexed and not stored. You will loose the data in those fields.
</para>
</listitem>
<listitem>
<para>
The best way to use update queries is also related to your Solr config.
If you are for instance using the autocommit feature of Solr you probably don't want to use a commit command in your update queries.
Make sure you are fully aware of configuration of the Solr core you are using.
</para>
</listitem>
</itemizedlist>
<sect1>
<title>Building an update query</title>
<para>
An update query has options and commands.
You can look at the commands and options as your instructions for the client classes to build an execute a request and return the correct result.
In the following sections both the options and commands will be discussed in detail.
You can also take a look at <ulinkurl="http://wiki.apache.org/solr/UpdateXmlMessages">http://wiki.apache.org/solr/UpdateXmlMessages</ulink> for more information about the underlying Solr update handler XML request format.
</para>
<sect2>
<title>Options</title>
<para>
The update query has only two options, and it's not likely you need alter them.
For select queries it's not uncommon to have a custom Solr handler, or a custom resultclass that maps to your models.
But for an update query you usually just want to use the default handler and check the result.
For this the default settings are just fine.
</para>
<para>However, if you do need to customize them for a special case, you can.</para>
<sect3>
<title>ResultClass</title>
<para>
If you want to use a custom result class you can set the class name with this option. The default value is 'Solarium_Result_Update'.
Any custom result class should extend this class to ensure full compatibility with the client classes.
It is your responsibility to make sure this class is included (or available through autoloading).
</para>
</sect3>
<sect3>
<title>Handler</title>
<para>
The handler is used for building the Solr URL. The default value is 'update' and it's very uncommon to need to change this.
But if you have a special update handler configured in your Solr core you can use this option to route update requests to this handler.
</para>
<para>
The handler value should not start or end with a slash, but may contain slashes. For instance 'admin/ping' for the ping handler is valid.
</para>
</sect3>
</sect2>
<sect2>
<title>Commands</title>
<para>Commands are the most important part of an update request.
An update request may contain any combination of commands in any order.
The commands will be added to the request in the exact order that you add them, and will be executed by Solr in exactly that order.
</para>
<para>
So if you were to add a 'delete' command followed by a 'rollback' command than the delete command will have no effect. (assuming there is no autocommit on the Solr server)
</para>
<sect3>
<title>Add</title>
<para>TODO</para>
</sect3>
<sect3>
<title>Delete</title>
<para>TODO</para>
</sect3>
<sect3>
<title>Commit</title>
<para>
This command commits any buffered commands to the index. This buffering is done by the Solr server, depending on the configuration.
It's a global buffer, so a commit command might also commit commands that where buffered from a previous update request that had no commit command.
</para>
<para>
If you use the autoCommit feature on the Solr core you probably don't want to use the commit command, because that would trigger a commit in between the autoCommit interval.
In all other cases it makes sense to add a commit to your update (or at least to the last update request if you issue multiple) to apply your update to the Solr index.
</para>
<para>
This command command starts the commit process on the server, bit the actual commit process might take a while.
If your update command with a commit returns successfully this only means Solr received the commands and is processing them, the result might not be visible for a while.
The time this takes depends on many factors: hardware, index size, number of index segments, the commands to execute, the search load, etcetera. It can vary between milliseconds and minutes.
</para>
<para>
TODO options
</para>
<para>
TODO addCommit
</para>
<para>
TODO add commit instance
</para>
</sect3>
<sect3>
<title>Optimize</title>
<para>TODO</para>
</sect3>
<sect3>
<title>Rollback</title>
<para>TODO</para>
</sect3>
</sect2>
<sect2>
<title>Usage modes</title>
<para>TODO (build command and add or use one of the helper methods)</para>
</sect2>
<sect2>
<title>Recommendations</title>
<para>TODO (command order, combining same commands into a single command, don't build too big updates)</para>
