From bb46d0594e82fe4a2f9682705be822b71cc56e33 Mon Sep 17 00:00:00 2001
From: Klimov Paul <klimov.paul@gmail.com>
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 <klimov.paul@gmail.com>
* @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 <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) {
- $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 <klimov.paul@gmail.com>
* @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
--
libgit2 0.27.1