From bb46d0594e82fe4a2f9682705be822b71cc56e33 Mon Sep 17 00:00:00 2001 From: Klimov Paul Date: Wed, 20 Nov 2013 20:24:56 +0200 Subject: [PATCH] Sphinx documentation updated. --- extensions/sphinx/ActiveQuery.php | 42 ++++++++++++++++- extensions/sphinx/ActiveRecord.php | 88 +++++++++++++++++++----------------- extensions/sphinx/ActiveRelation.php | 2 +- extensions/sphinx/Connection.php | 4 +- extensions/sphinx/Query.php | 4 +- extensions/sphinx/README.md | 18 +++++++- 6 files changed, 109 insertions(+), 49 deletions(-) diff --git a/extensions/sphinx/ActiveQuery.php b/extensions/sphinx/ActiveQuery.php index aaaf419..a196b56 100644 --- a/extensions/sphinx/ActiveQuery.php +++ b/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 * @since 2.0 diff --git a/extensions/sphinx/ActiveRecord.php b/extensions/sphinx/ActiveRecord.php index 15ef719..8364395 100644 --- a/extensions/sphinx/ActiveRecord.php +++ b/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 * @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) { - $this->_snippet = $this->fetchSnippet($query, $options); + if ($match !== null) { + $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->name = $name; - * $customer->email = $email; + * $customer = new Article; // or $customer = Article::find(['id' => $id]); + * $customer->id = $id; + * $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. - * - * If the table's primary key is auto-incremental and is null during insertion, - * it will be populated with the actual value after insertion. + * Only the [[changedAttributes|changed attribute values]] will be inserted. * - * For example, to insert a customer record: + * For example, to insert an article record: * * ~~~ - * $customer = new Customer; - * $customer->name = $name; - * $customer->email = $email; - * $customer->insert(); + * $article = new Article; + * $article->id = $id; + * $article->genre_id = $genreId; + * $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); - * $customer->name = $name; - * $customer->email = $email; - * $customer->update(); + * $article = Article::find(['id' => $id]); + * $article->genre_id = $genreId; + * $article->group_id = $groupId; + * $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 */ diff --git a/extensions/sphinx/ActiveRelation.php b/extensions/sphinx/ActiveRelation.php index 15a5ba0..c0dd0ca 100644 --- a/extensions/sphinx/ActiveRelation.php +++ b/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 * @since 2.0 diff --git a/extensions/sphinx/Connection.php b/extensions/sphinx/Connection.php index c0d4562..dbbe27a 100644 --- a/extensions/sphinx/Connection.php +++ b/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: diff --git a/extensions/sphinx/Query.php b/extensions/sphinx/Query.php index 4da378e..ff0dcba 100644 --- a/extensions/sphinx/Query.php +++ b/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; /** diff --git a/extensions/sphinx/README.md b/extensions/sphinx/README.md index e135318..35c400a 100644 --- a/extensions/sphinx/README.md +++ b/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. \ No newline at end of file +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' => '', + ], + ], +]; +``` \ No newline at end of file