INSTALL

 $Id: README.INSTALLATION 300651 2010-06-22 04:29:35Z iekpo $

================================================================================
PHP VERSION Dependencies
================================================================================

PHP version 5.2.3 or later is needed

================================================================================
Extension Dependencies
================================================================================
CURL extension
LIBXML extension

================================================================================
Library Dependencies
================================================================================

libxml2 2.6.26 or later is required

libcurl 7.15.0 or later is required

================================================================================
On UNIX
================================================================================

As mentioned before, the libxml and curl extensions must be enabled for the Apache Solr extension to be functional.

Do not attempt to hack the code to make it compile. It will fail, possibly with errors that could be hard to debug

To install the Apache Solr extension directly from PECL, please enter the following command, then follow the prompts

pecl install solr-beta

To compile from source, please follow the following steps

./configure

make && make install

This should compile the code and install it in the extension_dir specified in the ini file.

Then open your php.ini file and add the following line to it

extension=solr.so

Then restart your webserver. For CLI only, you do not have to restart your webserver.

Note :

If your system does not have the minimum version of the libcurl or libxml libraries, you can download the libraries

and compile them from source into a separate install prefix.

wget http://curl.haxx.se/download/curl-7.19.6.tar.gz

tar -zxvf curl-7.19.6.tar.gz

cd curl-7.19.6

configure --prefix=/root/custom/software

make && make install

cd ..

wget ftp://xmlsoft.org/libxml2/libxml2-2.7.6.tar.gz

tar -zxvf libxml2-2.7.6.tar.gz

cd libxml2-2.7.6

configure --prefix=/root/custom/software

make && make install

This example assumes that the libxml2 and libcurl libraries were compiled from source

and installed using "/root/custom/software" as the --prefix

So the absolute path to the easy.h header file will be 

/root/custom/software/include/curl/easy.h

And the absolute path to the libxml/parser.h header file wil be 

/root/custom/software/include/libxml2/libxml/parser.h

The absolute path to the xml2-config script will be /root/custom/software/bin/xml2-config

And the absolute path to the curl-config script will be /root/custom/software/bin/curl-config

Then you can pass libcurl prefix to the configure script for CURL and LIBXML respectively 

during the configuration phase as shown here :

4B ./configure --enable-solr --with-curl=/root/custom/software --with-libxml-dir=/root/custom/software

If you already have the latest versions of the libraries then the step listed in 4A alone is sufficient.

5. make && make install
 
This should compile the code and install it in the extension_dir specified in the ini file.

Then open your php.ini file and add the following line to it

extension=solr.so

If you would prefer to compile the Solr extension statically into php,

you will need to follow the following steps.

1. copy the solr_xxx folder into the ext folder in the php source

2. Include the --enable-solr flag as one of the options when configuring php

This will build the Solr extension statically into php.

After the installation is completed, you will have to restart your webserver for the changes to take effect. 

For CLI only use, you do not have to restart your webserver.

================================================================================
On Windows
================================================================================

If you are using a pre-compiled dll, simply copy the php_solr.dll file 
to your extension_dir specified in the ini file.

Then open your php.ini file and add the following line to it

extension=php_solr.dll

Then restart your webserver. For CLI only, you do not have to restart your webserver.

If you are building from source, you will need to download the library dependencies
for libxml and libcurl from the following link to the deps folder before 
running buildconf.bat 

http://wiki.php.net/internals/windows/libs

http://pecl2.php.net/downloads/php-windows-builds/php-libs/

More details are avialable here

http://wiki.php.net/internals/windows

Windows DLLs are now available here

http://downloads.php.net/pierre/

If you are building from source, you will need to download the library dependencies
for libxml and libcurl from the following link to the deps folder before 
running buildconf.bat

The Apache Solr extension can be compiled statically or shared.

- Shared compilation creates a php_solr.dll file.
- Static compilation puts the Solr extension directly into PHP (therefore it does not need to be loaded and cannot be unloaded).

You can toggle between compiling statically or as library by adding =static or =shared to the configure.js command during the compilation.

configure --with-solr=static

configure --with-solr=shared

- In the first configure command, the Apache Solr extension will be included in PHP
- In the second configure command, the Apache Solr extension will be compiled as separate DLL

Here is a more detail list of steps to follow :

1. Get visual studio 2008 ((express edition or professional) and install it.
2. Get and install windows sdk 6.1.
3. Get a php 5.3 snapshot (do not extract yet!).
4. Create the folder "c:\php-sdk"
5. Unpack the binary tools archive into this directory, there should be one sub-directory called "bin" and one called "script"
6. Open the "windows sdk 6.1 shell" (which is available from the start menu group) and execute the following commands in it:

setenv /x86 /xp /release
cd c:\php-sdk\
bin\phpsdk_setvars.bat
bin\phpsdk_buildtree.bat php53dev

7. Now extract the snapshot from Step 3 to C:\php-sdk\php53dev\vc9\x86 with your favourite unpacker so that the following directory gets created: 

C:\php-sdk\php53dev\vc9\x86\php5.3-xyz

8. run in the windows-sdk-shell:
cd C:\php-sdk\php53dev\vc9\x86\php5.3-xyz
buildconf

9. now run configure --help, to get an overview of the compiling flags

10. configure --disable-all --enable-cli --with-solr=yes --with-curl=yes --with-libxml=yes

11. nmake

If you are using Visual Studio 2005, use vc8 wherever you see vc9.

If you are on a 64-bit system, use x64 instead of x86.

The following resources can provide you with more information :

http://wiki.php.net/internals/windows/libs

http://pecl2.php.net/downloads/php-windows-builds/php-libs/

More details are avialable here :

http://wiki.php.net/internals/windows

The binary tools archive is available at :

http://pecl2.php.net/downloads/php-windows-builds/php-libs/binary-tools.zip

Windows SDK 6.1 is available at :

http://www.microsoft.com/downloads/details.aspx?FamilyId=E6E1C3DF-A74F-4207-8586-711EBE331CDC&displaylang=en

The PHP 5.3 shapshot is available at:

http://windows.php.net/downloads/snaps/php-5.3/php-5.3-src-latest.zip

================================================================================
PHP NATIVE RESPONSE WRITER
================================================================================

A new response writer for php is now available at https://issues.apache.org/jira/browse/SOLR-1967

This new feature adds a new response writer class to the org.apache.solr.request package.

This class is used by the PHP Native Solr Client driver to prepare the query response from Solr.

This response writer allows you to configure the way the data is serialized for the PHP client.

You can use your own class name and you can also control how the properties are serialized as well.

You can pass the objectClassName request parameter to specify the class name to be used for serializing objects. Please note that the class must be available on the client side to avoid a PHP_Incomplete_Object error during the unserialization process.

You can also pass in the objectPropertiesStorageMode request parameter with either a 0 (independent properties) or a 1 (combined properties).

These parameters can also be passed as a named list when loading the response writer in the solrconfig.xml file

Having this control allows you to create custom objects which gives the flexibility of implementing custom __get methods, ArrayAccess, Traversable and Iterator interfaces on the PHP client side.

Until this class in incorporated into Solr, you simply have to copy the jar file containing this plugin into your lib directory under $SOLR_HOME

Then set up the configuration as shown below and then restart your servelet container

Below is an example configuration in solrconfig.xml

<code>
<queryResponseWriter name="phpnative" class="org.apache.solr.request.PHPNativeResponseWriter">
<!-- You can choose a different class for your objects. Just make sure the class is available in the client -->
<str name="objectClassName">SolrObject</str>
<!--
0 means OBJECT_PROPERTIES_STORAGE_MODE_INDEPENDENT
1 means OBJECT_PROPERTIES_STORAGE_MODE_COMBINED

In independed mode, each property is a separate property
In combined mode, all the properites are merged into a _properties array.
The combined mode allows you to create custom __getters and you could also implement ArrayAccess, Iterator and Traversable
-->
<int name="objectPropertiesStorageMode">0</int>
</queryResponseWriter

<code>

Below is an example implementation on the PHP client side.

Support for specifying custom response writers will be available starting from the 0.9.11 version of the PECL extension for Solr currently available in trunk

<code>
<?php

class SolrClass
{
public $_properties = array();

public function __get($property_name) {

if (property_exists($this, $property_name)) { return $this->$property_name; } else if (isset($_properties[$property_name])) { return $_properties[$property_name]; }

return null;
}
}

$options = array
(
'hostname' => 'localhost',
'port' => 8983,
'path' => '/solr/'
);

$client = new SolrClient($options);

$client->setResponseWriter("phpnative");

$response = $client->ping();

$query = new SolrQuery();

$query->setQuery(":");

$query->set("objectClassName", "SolrClass");
$query->set("objectPropertiesStorageMode", 1);

$response = $client->query($query);

$resp = $response->getResponse();

?>
<code>

================================================================================
How to Report Bugs
================================================================================

Please report bugs to iekpo@php.net

You can also register bugs here 

http://pecl.php.net/bugs/report.php?package=solr

Thank you for using PHP