Docs for Sphinx extension updated

extensions/sphinx/Query.php

@@ -386,12 +386,12 @@ class Query extends Component implements QueryInterface
      * MATCH operator inside the WHERE clause.
      * Note: this value will be processed by [[Connection::escapeMatchValue()]],
      * if you need to compose complex match condition use [[Expression]]:
-     * ```
+     * ~~~
      * $query = new Query;
      * $query->from('my_index')
      *     ->match(new Expression(':match', ['match' => '@(content) ' . Yii::$app->sphinx->escapeMatchValue($matchValue)]))
      *     ->all();
-     * ```
+     * ~~~
      *
      * @param string $query fulltext query text.
      * @return static the query object itself

extensions/sphinx/README.md

@@ -120,12 +120,6 @@ $rows = $query->from('idx_item')
   escape any special characters, which may break the query.
 
 
-Snippets
---------
-
-TODO
-
-
 Using the ActiveRecord
 ----------------------
 
@@ -181,3 +175,71 @@ $provider = new ActiveDataProvider([
 ]);
 $models = $provider->getModels();
 ```
+
+
+Building Snippets (Excerpts)
+----------------------------
+
+Snippet (excerpt) - is a fragment of the index source text, which contains highlighted words from fulltext search
+condition. Sphinx has a powerful build-in mechanism to compose snippets. However, since Sphinx does not store the
+original indexed text, the snippets for the rows in query result should be build separately via another query.
+Such query may be performed via `yii\sphinx\Command::callSnippets()`:
+
+```php
+$sql = "SELECT * FROM idx_item WHERE MATCH('about')";
+$rows = Yii::$app->sphinx->createCommand($sql)->queryAll();
+
+$rowSnippetSources = [];
+foreach ($rows as $row) {
+    $rowSnippetSources[] = file_get_contents('/path/to/index/files/' . $row['id'] . '.txt');
+}
+
+$snippets = Yii::$app->sphinx->createCommand($sql)->callSnippets('idx_item', $rowSnippetSources, 'about');
+```
+
+You can simplify this workflow using [[yii\sphinx\Query::snippetCallback]].
+It is a PHP callback, which receives array of query result rows as an argument and must return the
+array of snippet source strings in the order, which match one of incoming rows.
+Example:
+
+```php
+use yii\sphinx\Query;
+
+$query = new Query;
+$rows = $query->from('idx_item')
+    ->match($_POST['search'])
+    ->snippetCallback(function ($rows) {
+        $result = [];
+        foreach ($rows as $row) {
+            $result[] = file_get_contents('/path/to/index/files/' . $row['id'] . '.txt');
+        }
+        return $result;
+    })
+    ->all();
+
+foreach ($rows as $row) {
+    echo $row['snippet'];
+}
+```
+
+If you are using Active Record, you can [[yii\sphinx\ActiveQuery::snippetByModel()]] to compose a snippets.
+This method retrieves snippet source per each row calling `getSnippetSource()` method of the result model.
+All you need to do is implement it in your Active Record class, so it return the correct value:
+
+```php
+use yii\sphinx\ActiveRecord;
+
+class Article extends ActiveRecord
+{
+    public function getSnippetSource()
+    {
+        return file_get_contents('/path/to/source/files/' . $this->id . '.txt');;
+    }
+}
+
+$articles = Article::find()->snippetByModel()->all();
+
+foreach ($articles as $article) {
+    echo $article->snippet;
+}
+```