Sphinx documentation updated.

extensions/sphinx/ActiveQuery.php

@@ -11,7 +11,47 @@ use yii\db\ActiveQueryInterface;
 use yii\db\ActiveQueryTrait;
 
 /**
- * Class ActiveQuery
+ * ActiveQuery represents a Sphinx query associated with an Active Record class.
+ *
+ * ActiveQuery instances are usually created by [[ActiveRecord::find()]] and [[ActiveRecord::findBySql()]].
+ *
+ * Because ActiveQuery extends from [[Query]], one can use query methods, such as [[where()]],
+ * [[orderBy()]] to customize the query options.
+ *
+ * ActiveQuery also provides the following additional query options:
+ *
+ * - [[with()]]: list of relations that this query should be performed with.
+ * - [[indexBy()]]: the name of the column by which the query result should be indexed.
+ * - [[asArray()]]: whether to return each record as an array.
+ *
+ * These options can be configured using methods of the same name. For example:
+ *
+ * ~~~
+ * $articles = Article::find()->with('source')->asArray()->all();
+ * ~~~
+ *
+ * ActiveQuery allows to build the snippets using sources provided by ActiveRecord.
+ * You can use [[snippetByModel()]] method to enable this.
+ * For example:
+ *
+ * ~~~
+ * class Article extends ActiveRecord
+ * {
+ *     public function getSource()
+ *     {
+ *         return $this->hasOne('db', ArticleDb::className(), ['id' => 'id']);
+ *     }
+ *
+ *     public function getSnippetSource()
+ *     {
+ *         return $this->source->content;
+ *     }
+ *
+ *     ...
+ * }
+ *
+ * $articles = Article::find()->with('source')->snippetByModel()->all();
+ * ~~~
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0

extensions/sphinx/ActiveRecord.php

@@ -30,6 +30,7 @@ use Yii;
  * @property array $populatedRelations An array of relation data indexed by relation names. This property is
  * read-only.
  * @property integer $primaryKey The primary key value. This property is read-only.
+ * @property string $snippet current snippet value for this Active Record instance..
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0
@@ -103,7 +104,9 @@ class ActiveRecord extends Model
 	 */
 	private $_related = [];
 	/**
-	 * @var string snippet value for this Active Record instance.
+	 * @var string current snippet value for this Active Record instance.
+	 * It will be filled up automatically when instance found using [[Query::snippetCallback]]
+	 * or [[ActiveQuery::snippetByModel()]].
 	 */
 	private $_snippet;
 
@@ -302,27 +305,28 @@ class ActiveRecord extends Model
 	}
 
 	/**
-	 * @param string $query snippet source query
+	 * Returns current snippet value or generates new one from given match.
+	 * @param string $match snippet source query
 	 * @param array $options list of options in format: optionName => optionValue
 	 * @return string snippet value
 	 */
-	public function getSnippet($query = null, $options = [])
+	public function getSnippet($match = null, $options = [])
 	{
-		if ($query !== null) {
+		if ($match !== null) {
-			$this->_snippet = $this->fetchSnippet($query, $options);
+			$this->_snippet = $this->fetchSnippet($match, $options);
 		}
 		return $this->_snippet;
 	}
 
 	/**
 	 * Builds up the snippet value from the given query.
-	 * @param string $query the full-text query to build snippets for.
+	 * @param string $match the full-text query to build snippets for.
 	 * @param array $options list of options in format: optionName => optionValue
 	 * @return string snippet value.
 	 */
-	protected function fetchSnippet($query, $options = [])
+	protected function fetchSnippet($match, $options = [])
 	{
-		return static::callSnippets($this->getSnippetSource(), $query, $options);
+		return static::callSnippets($this->getSnippetSource(), $match, $options);
 	}
 
 	/**
@@ -330,12 +334,12 @@ class ActiveRecord extends Model
 	 * Active Record instance.
 	 * Child classes must implement this method to return the actual snippet source text.
 	 * For example:
-	 * ```php
+	 * ~~~
 	 * public function getSnippetSource()
 	 * {
 	 *     return $this->snippetSourceRelation->content;
 	 * }
-	 * ```
+	 * ~~~
 	 * @return string snippet source string.
 	 * @throws \yii\base\NotSupportedException if this is not supported by the Active Record class
 	 */
@@ -364,6 +368,9 @@ class ActiveRecord extends Model
 	 *    and implement necessary business logic (e.g. merging the changes, prompting stated data)
 	 *    to resolve the conflict.
 	 *
+	 * Warning: optimistic lock will NOT work in case of updating fields (not attributes) for the
+	 * runtime indexes!
+	 *
 	 * @return string the column name that stores the lock version of a table row.
 	 * If null is returned (default implemented), optimistic locking will not be supported.
 	 */
@@ -373,10 +380,10 @@ class ActiveRecord extends Model
 	}
 
 	/**
-	 * Declares which DB operations should be performed within a transaction in different scenarios.
+	 * Declares which operations should be performed within a transaction in different scenarios.
 	 * The supported DB operations are: [[OP_INSERT]], [[OP_UPDATE]] and [[OP_DELETE]],
 	 * which correspond to the [[insert()]], [[update()]] and [[delete()]] methods, respectively.
-	 * By default, these methods are NOT enclosed in a DB transaction.
+	 * By default, these methods are NOT enclosed in a transaction.
 	 *
 	 * In some scenarios, to ensure data consistency, you may want to enclose some or all of them
 	 * in transactions. You can do so by overriding this method and returning the operations
@@ -763,20 +770,21 @@ class ActiveRecord extends Model
 	 * This method will call [[insert()]] when [[isNewRecord]] is true, or [[update()]]
 	 * when [[isNewRecord]] is false.
 	 *
-	 * For example, to save a customer record:
+	 * For example, to save an article record:
 	 *
 	 * ~~~
-	 * $customer = new Customer;  // or $customer = Customer::find($id);
+	 * $customer = new Article;  // or $customer = Article::find(['id' => $id]);
-	 * $customer->name = $name;
+	 * $customer->id = $id;
-	 * $customer->email = $email;
+	 * $customer->genre_id = $genreId;
+	 * $customer->content = $email;
 	 * $customer->save();
 	 * ~~~
 	 *
 	 *
 	 * @param boolean $runValidation whether to perform validation before saving the record.
-	 * If the validation fails, the record will not be saved to database.
+	 * If the validation fails, the record will not be saved.
 	 * @param array $attributes list of attributes that need to be saved. Defaults to null,
-	 * meaning all attributes that are loaded from DB will be saved.
+	 * meaning all attributes that are loaded from index will be saved.
 	 * @return boolean whether the saving succeeds
 	 */
 	public function save($runValidation = true, $attributes = null)
@@ -789,7 +797,7 @@ class ActiveRecord extends Model
 	}
 
 	/**
-	 * Inserts a row into the associated database table using the attribute values of this record.
+	 * Inserts a row into the associated Sphinx index using the attribute values of this record.
 	 *
 	 * This method performs the following steps in order:
 	 *
@@ -798,31 +806,29 @@ class ActiveRecord extends Model
 	 * 2. call [[afterValidate()]] when `$runValidation` is true.
 	 * 3. call [[beforeSave()]]. If the method returns false, it will skip the
 	 *    rest of the steps;
-	 * 4. insert the record into database. If this fails, it will skip the rest of the steps;
+	 * 4. insert the record into index. If this fails, it will skip the rest of the steps;
 	 * 5. call [[afterSave()]];
 	 *
 	 * In the above step 1, 2, 3 and 5, events [[EVENT_BEFORE_VALIDATE]],
 	 * [[EVENT_BEFORE_INSERT]], [[EVENT_AFTER_INSERT]] and [[EVENT_AFTER_VALIDATE]]
 	 * will be raised by the corresponding methods.
 	 *
-	 * Only the [[changedAttributes|changed attribute values]] will be inserted into database.
+	 * Only the [[changedAttributes|changed attribute values]] will be inserted.
-	 *
-	 * If the table's primary key is auto-incremental and is null during insertion,
-	 * it will be populated with the actual value after insertion.
 	 *
-	 * For example, to insert a customer record:
+	 * For example, to insert an article record:
 	 *
 	 * ~~~
-	 * $customer = new Customer;
+	 * $article = new Article;
-	 * $customer->name = $name;
+	 * $article->id = $id;
-	 * $customer->email = $email;
+	 * $article->genre_id = $genreId;
-	 * $customer->insert();
+	 * $article->content = $content;
+	 * $article->insert();
 	 * ~~~
 	 *
 	 * @param boolean $runValidation whether to perform validation before saving the record.
-	 * If the validation fails, the record will not be inserted into the database.
+	 * If the validation fails, the record will not be inserted.
 	 * @param array $attributes list of attributes that need to be saved. Defaults to null,
-	 * meaning all attributes that are loaded from DB will be saved.
+	 * meaning all attributes that are loaded from index will be saved.
 	 * @return boolean whether the attributes are valid and the record is inserted successfully.
 	 * @throws \Exception in case insert failed.
 	 */
@@ -877,7 +883,7 @@ class ActiveRecord extends Model
 	}
 
 	/**
-	 * Saves the changes to this active record into the associated database table.
+	 * Saves the changes to this active record into the associated Sphinx index.
 	 *
 	 * This method performs the following steps in order:
 	 *
@@ -886,7 +892,7 @@ class ActiveRecord extends Model
 	 * 2. call [[afterValidate()]] when `$runValidation` is true.
 	 * 3. call [[beforeSave()]]. If the method returns false, it will skip the
 	 *    rest of the steps;
-	 * 4. save the record into database. If this fails, it will skip the rest of the steps;
+	 * 4. save the record into index. If this fails, it will skip the rest of the steps;
 	 * 5. call [[afterSave()]];
 	 *
 	 * In the above step 1, 2, 3 and 5, events [[EVENT_BEFORE_VALIDATE]],
@@ -895,13 +901,13 @@ class ActiveRecord extends Model
 	 *
 	 * Only the [[changedAttributes|changed attribute values]] will be saved into database.
 	 *
-	 * For example, to update a customer record:
+	 * For example, to update an article record:
 	 *
 	 * ~~~
-	 * $customer = Customer::find($id);
+	 * $article = Article::find(['id' => $id]);
-	 * $customer->name = $name;
+	 * $article->genre_id = $genreId;
-	 * $customer->email = $email;
+	 * $article->group_id = $groupId;
-	 * $customer->update();
+	 * $article->update();
 	 * ~~~
 	 *
 	 * Note that it is possible the update does not affect any row in the table.
@@ -1012,13 +1018,13 @@ class ActiveRecord extends Model
 	}
 
 	/**
-	 * Deletes the table row corresponding to this active record.
+	 * Deletes the index entry corresponding to this active record.
 	 *
 	 * This method performs the following steps in order:
 	 *
 	 * 1. call [[beforeDelete()]]. If the method returns false, it will skip the
 	 *    rest of the steps;
-	 * 2. delete the record from the database;
+	 * 2. delete the record from the index;
 	 * 3. call [[afterDelete()]].
 	 *
 	 * In the above step 1 and 3, events named [[EVENT_BEFORE_DELETE]] and [[EVENT_AFTER_DELETE]]
@@ -1298,8 +1304,6 @@ class ActiveRecord extends Model
 	 * This method is called by [[create()]].
 	 * You may override this method if the instance being created
 	 * depends on the row data to be populated into the record.
-	 * For example, by creating a record based on the value of a column,
-	 * you may implement the so-called single-table inheritance mapping.
 	 * @param array $row row data to be populated into the record.
 	 * @return ActiveRecord the newly created active record
 	 */

extensions/sphinx/ActiveRelation.php

@@ -11,7 +11,7 @@ use yii\db\ActiveRelationInterface;
 use yii\db\ActiveRelationTrait;
 
 /**
- * Class ActiveRelation
+ * ActiveRelation represents a relation to Sphinx Active Record class.
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0

extensions/sphinx/Connection.php

@@ -14,13 +14,13 @@ use yii\base\NotSupportedException;
  * Note: although PDO supports numerous database drivers, this class supports only MySQL.
  *
  * In order to setup Sphinx "searchd" to support MySQL protocol following configuration should be added:
- * ```
+ * ~~~
  * searchd
  * {
  *     listen = localhost:9306:mysql41
  *     ...
  * }
- * ```
+ * ~~~
  *
  * The following example shows how to create a Connection instance and establish
  * the Sphinx connection:

extensions/sphinx/Query.php

@@ -101,7 +101,7 @@ class Query extends Component implements QueryInterface
 	 * Such callback will receive 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.
 	 * For example:
-	 * ```php
+	 * ~~~
 	 * $query = new Query;
 	 * $query->from('idx_item')
 	 *     ->match('pencil')
@@ -113,7 +113,7 @@ class Query extends Component implements QueryInterface
 	 *         return $result;
 	 *     })
 	 *     ->all();
-	 * ```
+	 * ~~~
 	 */
 	public $snippetCallback;
 	/**

extensions/sphinx/README.md

@@ -50,4 +50,20 @@ searchd
 
 This extension supports all Sphinx features including [Runtime Indexes](http://sphinxsearch.com/docs/current.html#rt-indexes).
 Since this extension uses MySQL protocol to access Sphinx, it shares base approach and much code from the
-regular "yii\db" package.
+regular "yii\db" package.
+
+To use this extension, simply add the following code in your application configuration:
+
+```php
+return [
+	//....
+	'components' => [
+		'sphinx' => [
+			'class' => 'yii\sphinx\Connection',
+			'dsn' => 'mysql:host=127.0.0.1;port=9306;',
+			'username' => '',
+			'password' => '',
+		],
+	],
+];
+```