Added Query Elevation Component (#597)

* Added Query Elevation Component

* Added docs for Query Elevation Component

* Added integration test against techproducts

docs/queries/select-query/building-a-select-query/components/query-elevation-component.md

@@ -0,0 +1,73 @@
+Query Elevation is a Solr component that lets you configure the top results for a given query regardless of the normal Lucene scoring. Elevated query results can be configured in an external XML file or at request time. For more info see <https://lucene.apache.org/solr/guide/the-query-elevation-component.html>.
+
+Options
+-------
+
+| Name            | Type    | Default value | Description                                                                                                                                            |
+|-----------------|---------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| transformers    | string  | [elevated]    | Comma separated list of transformers to annotate each document. The [elevated] transformer tells whether or not the document was elevated.             |
+| enableElevation | boolean | null          | For debugging it may be useful to see results with and without elevation applied. To get results without elevation, use false.                         |
+| forceElevation  | boolean | null          | By default, this component respects the requested sort parameter. To return elevated documents first, use true.                                        |
+| exclusive       | boolean | null          | You can force Solr to return only the results specified in the elevation file by using true.                                                           |
+| markExcludes    | boolean | null          | You can include documents that the elevation configuration would normally exclude by using true. The [excluded] transformer is added to each document. |
+| elevateIds      | string  | null          | Comma separated list of documents to elevate. This overrides the elevations _and_ exclusions that are configured for the query in the elevation file.  |
+| excludeIds      | string  | null          | Comma separated list of documents to exclude. This overrides the elevations _and_ exclusions that are configured for the query in the elevation file.  |
+||
+
+Example
+-------
+
+```php
+<?php
+
+require(__DIR__.'/init.php');
+htmlHeader();
+
+// create a client instance
+$client = new Solarium\Client($config);
+
+// get a select query instance
+$query = $client->createSelect();
+$query->setQuery('electronics');
+
+// set a handler that is configured with an elevator component in solrconfig.xml (or add it to your default handler)
+$query->setHandler('elevate');
+
+// get query elevation component
+$elevate = $query->getQueryElevation();
+
+// return elevated documents first
+$elevate->setForceElevation(true);
+
+// specify documents to elevate and/or exclude if you don't use an elevation file or want to override it at request time
+$elevate->setElevateIds(array('VS1GB400C3', 'VDBDB1A16'));
+$elevate->setExcludeIds(array('SP2514N', '6H500F0'));
+
+// document transformers can be omitted from the results
+//$elevate->clearTransformers();
+
+// this executes the query and returns the result
+$resultset = $client->select($query);
+// display the total number of documents found by solr
+echo 'NumFound: '.$resultset->getNumFound();
+
+// show documents using the resultset iterator
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+
+    // the documents are also iterable, to get all fields
+    foreach ($document as $field => $value) {
+        // this converts multivalue fields to a comma-separated string
+        if (is_array($value)) {
+            $value = implode(', ', $value);
+        }
+
+        echo '<tr><th>' . $field . '</th><td>' . $value . '</td></tr>';
+    }
+
+}
+
+htmlFooter();
+
+```

examples/2.1.5.12-queryelevation.php

@@ -0,0 +1,51 @@
+<?php
+
+require(__DIR__.'/init.php');
+htmlHeader();
+
+// create a client instance
+$client = new Solarium\Client($config);
+
+// get a select query instance
+$query = $client->createSelect();
+$query->setQuery('electronics');
+
+// set a handler that is configured with an elevator component in solrconfig.xml (or add it to your default handler)
+$query->setHandler('elevate');
+
+// get query elevation component
+$elevate = $query->getQueryElevation();
+
+// return elevated documents first
+$elevate->setForceElevation(true);
+
+// specify documents to elevate and/or exclude if you don't use an elevation file or want to override it at request time
+$elevate->setElevateIds(array('VS1GB400C3', 'VDBDB1A16'));
+$elevate->setExcludeIds(array('SP2514N', '6H500F0'));
+
+// document transformers can be omitted from the results
+//$elevate->clearTransformers();
+
+// this executes the query and returns the result
+$resultset = $client->select($query);
+// display the total number of documents found by solr
+echo 'NumFound: '.$resultset->getNumFound();
+
+// show documents using the resultset iterator
+foreach ($resultset as $document) {
+
+    echo '<hr/><table>';
+
+    // the documents are also iterable, to get all fields
+    foreach ($document as $field => $value) {
+        // this converts multivalue fields to a comma-separated string
+        if (is_array($value)) {
+            $value = implode(', ', $value);
+        }
+
+        echo '<tr><th>' . $field . '</th><td>' . $value . '</td></tr>';
+    }
+
+}
+
+htmlFooter();

examples/index.html

@@ -58,6 +58,7 @@ <h1>Solarium examples</h1>
                         <li><a href="2.1.5.9-spellcheck.php">2.1.5.9 Spellcheck</a></li>
                         <li><a href="2.1.5.10-stats.php">2.1.5.10 Stats</a></li>
                         <li><a href="2.1.5.11-debug.php">2.1.5.11 Debug (DebugQuery)</a></li>
+                        <li><a href="2.1.5.12-queryelevation.php">2.1.5.12 Query Elevation</a></li>
                     </ul>
                     <li><a href="2.1.6-helper-functions.php">2.1.6 Helper functions</a></li>
                     <li><a href="2.1.7-query-reuse.php">2.1.7 Query re-use</a></li>

src/Component/ComponentAwareQueryInterface.php

@@ -72,6 +72,11 @@ interface ComponentAwareQueryInterface
      */
     const COMPONENT_TERMS = 'terms';
 
+    /**
+     * Query component queryelevation.
+     */
+    const COMPONENT_QUERYELEVATION = 'queryelevation';
+
     /**
      * Get all registered component types.
      *