================================================================================
Introducing the Solr PHP Extension
================================================================================
The Solr extension is an extremely fast, light-weight, feature-rich library that
allows PHP developers to communicate effectively with Solr server instances.

There are tools to add documents and make updates to the solr server.

It also contains tools that allows you to build advanced queries to the server
when searching for documents.

There are also special objects that simplifies the sending of name-value requests
to the server. This includes the SolrParams class and all its child classes.

The SolrClient object allows one to communicate with Solr containers that are
behind proxy servers or that require HTTP Authentication to proceed.

The SolrClient constructor accepts options such as
http authentication username and passwor, proxy server name, port, login and
passwords etc.

Using an advanced http client like libcurl allows us to leverage the features
available with the library. We can reuse the HTTP connections without having
to create a separate one for each request.

================================================================================
How to Install
================================================================================

Please refer to the README.INSTALLATION file.

================================================================================
Magic Methods and Interfaces Implemented
================================================================================

SolrDocument implements the following interfaces.

(1) ArrayAccess  - to access the fields as array keys using field names.
(2) Iterator	 - to iterate over the document fields using foreach()
(3) Serializable - provides custom serialization of the object.

SolrDocument also contains the __get and __set magic methods which allows developers
to access the fields directly. When setting fields, if the field already
has a value the new value will be appended to the list of values for that field.

Each field is a SolrDocumentField object with the following public properties :

(a) name - a string with name of the field.
(b) boost - a double representing the boost value of the field (intentionally empty)
(c) values - an array of all the field values as strings.

Custom Serialization

string SolrDocument::serialize(void) returns an XML document representing a
SolrDocument as shown below :

<?xml version="1.0" encoding="UTF-8"?>
<solr_document>
  <fields>
    <field name="id">
      <field_value>A0F43D</field_value>
    </field>
    <field name="name">
      <field_value>Israel Ekpo</field_value>
    </field>
    <field name="email">
      <field_value>Israel.Ekpo@israel.ekpo.com</field_value>
    </field>
    <field name="skills">
      <field_value>Reading</field_value>
      <field_value>Writing</field_value>
      <field_value>Soccer</field_value>
      <field_value>Teaching</field_value>
    </field>
    <field name="languages">
      <field_value>Inglés</field_value>
      <field_value>Espanól</field_value>
    </field>
  </fields>
</solr_document>

Here is a complete example of a serialized SolrDocument object:

C:12:"SolrDocument":679:{<?xml version="1.0" encoding="UTF-8"?>
<solr_document>
  <fields>
    <field name="id">
      <field_value>A0F43D</field_value>
    </field>
    <field name="name">
      <field_value>Israel Ekpo</field_value>
    </field>
    <field name="email">
      <field_value>Israel.Ekpo@israel.ekpo.com</field_value>
    </field>
    <field name="skills">
      <field_value>Reading</field_value>
      <field_value>Writing</field_value>
      <field_value>Soccer</field_value>
      <field_value>Teaching</field_value>
    </field>
    <field name="languages">
      <field_value>Inglés</field_value>
      <field_value>Espanól</field_value>
    </field>
  </fields>
</solr_document>
}

One of the items on my todo list is to create a response writer to return
serialized SolrDocument objects instead of document arrays.

SolrDocument::unserialize(string $serialized) accepts an XML document
representing the SolrDocument object. It will the bring the object back to live.

The SolrDocument class also has the method SolrDocument::getInputDocument() to
allow one do get the SolrInputDocument version of a SolrDocument instance.

This method may be helpful if one needs to resubmit the document to the server to
updates.

The Solr extension has the SolrQuery object (a child of SolrParams) that enables
the developer to send custom advanced name-value requests to the solr server.

The SolrQuery object can also be serialized and reused later, which makes it very
helpful to saving the state of the application across multiple requests. This may be
very useful in cases such as facet browsing where additional parameters may need to be
added to the current object or removed from it to get the desired results without
having to start over from scratch.

================================================================================
Parsing of XML Responses from the Solr Server
================================================================================
XML responses from the solr server are expected to be formatted using version 2.2
These xml documents are parsed into serialized php code and returned as
read-only SolrObject instances whose properties can also be accessed as array
keys in addition to being accessible directly via the object->member notation.

Having the properties accessible via object[member] notation is helpful in cases
where the property name is not valid (contains dots and other characters not
legal in php.

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

Please report bugs to http://bugs.php.net

If you experience a crash due to a segmentation fault, please follow the instructions on the link below
to get a gdb backtrace and then submit the trace in your bug report as well

http://bugs.php.net/bugs-generating-backtrace.php

Thank you for using PHP

================================================================================
Omar Shaban (omars@php.net)
================================================================================
 - Lead Maintainer
================================================================================

Thanks to all our [contributors](https://github.com/php/pecl-search_engine-solr/graphs/contributors).

================================================================================

These are the people that made version 1.0 release of the Apache Solr PECL extension possible.

If I have left anyone out or mis-stated your contributions, please let me know so that
it can be correct to reflect your contributions accurately.

Thanks again for making this possible.

================================================================================
Israel Ekpo (iekpo@php.net)
================================================================================
 - Orignal Author of the Apache Solr PECL extension
 - Orignal Extension Concept and Design
 - Lead Maintainer

================================================================================
Pierre-Alain Joye (pajoye@php.net)
================================================================================
 - Fine tuned and created the final version of the config.w32 script (291135)
 - Compiled and made available several versions of the .dll binaries for Windows.
 - Currently hosting the windows .dll binaries for the Apache Solr PECL extension.

================================================================================
Kalle Sommer Nielsen (kalle@php.net)
================================================================================
 - Significant refactoring of the config.w32 script for Windows (288890)
 - Corrected Windows C++ compiler bugs (288890)

================================================================================
Pierrick Charron (pierrick@php.net)
================================================================================
 - Assisted in the testing of the extension using various test cases.
 - Uncovered and reported several bugs due to his insight of the extension internals.
 - Discovered bugs 16943 and 16924
 - Patched the config.w32 for its first successful compilation on Windows (291101).

================================================================================
Felipe Pena (felipe@php.net)
================================================================================
 - Participated significantly after the intial release and uncovered a serious bug that lead to segfaults.
 - Discovered bugs 16855 thru 16859
 - Contributed to development of UNIX config.m4 script (289148)

================================================================================
Alex Samorukov (alexey.samorukov@varien.com)
================================================================================
 - Lowered minimum supported version for libcurl to 7.15.0
 - Lowered minimum supported version for libxml2 to 2.6.26

================================================================================
(trevor at blubolt dot com, max at blubolt dot com)
================================================================================
 - Fixed PECL Bug# 17172 MoreLikeThis only parses one doc

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

PHP version 5.3 or later is needed

================================================================================
Extension Dependencies
================================================================================
LIBXML extension
JSON 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

To compile from source, please follow the following steps

$ phpize

$ ./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

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

Please report bugs to omars@php.net

You can also register bugs here

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

Thank you for using PHP

================================================================================
Solr Notes about Memory Allocation and interaction with HashTables
================================================================================

The following notes are for C-space PHP developers.

If you are not really familiar with how the Zend HashTable API or the
memory allocation marcros really works, please take sometime to read the notes below :

This is correct as of Zend Engine version 2.3.0

- If memory was allocated with emalloc(), it has to be freed with efree().

- If memory was allocated using pemalloc(), the same value for the persistent
parameter must be used during pefree() to deallocated the allocated memory.
The memory manager for the Zend API will then decide whether to use free() or
efree() depending on whether persistent is 1 or 0 respectively. The same
principle applies to pestrdup(), pecalloc() and the other memory allocation
macros.

- When inserting values into the HashTables, if the value for the persistent
parameter is set, then the memory allocation for the entered item should be
persistent to i.e. pemalloc() with persistent set to 1.

The following will apply when adding new values into a HashTable for items
that were dynamically allocated :

(a) If the value for the nDataSize parameter is the size of that of a
pointer sizeof(void *), the HashTable API copies the contents of
the pData parameter into the Bucket->pDataPtr member for that data Bucket.
Then it sets the Bucket->pData member to the address of the Bucket->pDataPtr
member for that data Bucket.

(b) If the value for the nDataSize parameter is not equal to sizeof(void *),
the HashTable API allocates new memory for the Bucket->pData member using
the size equivalent to nDataSize and the same value for the persistent flag
set for the target HashTable. The the contents of the pData parameter is
copied into the Bucket->pData member in this newly allocated memory location.
Then the Bucket->pDataPtr member for this Bucket is set to NULL.

Do not worry about the newly allocated memory allocated by the HashTable API;
if the nDataSize parameter was not equal to sizeof(void *), then
during the cleanup process, the Zend API will free the new memory it allocated
during the insert process.

It will also call the destructor function if a valid one was passed when the
HashTable was initialized with zend_hash_init().

In the extension, I have used the p* version of the memory allocation functions
to allow me toggle if there is any need to do so in the future. This will prevent
a massive search and replace effort.

For all the HashTables, I set the intial size to 8 to reduce the looping when
zend_hash_init() is setting up the HashTable pointer to use.

================================================================================
Submitting contributions
================================================================================

A lot of time has been put into designing, implementing and documenting this extension.

A lot of work has also been put into ensuring that users of the extension
experience very minimal defects during usage.

New ideas, corrections, bug fixes, feature improvements are always welcome.

However, you must discuss any changes you are about to make to any of
the source files prior to making or submitting such changes either in the
PECL developers mailing list (pecl-dev@lists.php.net) or by contacting the
current author(s) or maintainer(s) of this extension directly.

Test scripts should be included when making the submissions.

Also explain thoroughly what has been fixed/added/changed by your patch.

If your patch is easy to review and has obviously no side-effects,
it might take up to a few hours until it is committed.

Since this is a volunteer-driven effort, more complex patches will
require more patience on the part of the submitter.

================================================================================
Testing thoroughly before submissions
================================================================================

This is a fairly large library and each component is dependent on another
component either directly or indirectly.

As a consequence, any and all changes must be tested thoroughly before commiting them.

It is only polite to the users, author(s) or maintainer(s) that you do so.

================================================================================
Checklist for making submissions
================================================================================

 - Did you run "make test" to check if your patch didn't break
   other features?
 - Did you compile PHP with --enable-debug and check the PHP and
   web server error logs when you test your patch?
 - Did you build PHP for multi-threaded web servers.
 - Did you create test script for "make test"? (Recommended)
 - Did you check your patch is unified format and it does not
   contain white space changes?
 - Did you read the patch again?