Skip to content

Y
yii2
Commit bb46d059 by Klimov Paul
Options

Sphinx documentation updated.

parent d1c87c7e
Showing with 110 additions and 50 deletions
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) {
$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
*/
......
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.
\ 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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment