Skip to content

Y
yii2
Commit d1c87c7e by Paul Klimov
Options

Sphinx documentation updated.

parent e19c9ceb
Showing with 220 additions and 84 deletions
extensions/sphinx/ActiveRecord.php
......@@ -14,14 +14,22 @@ use yii\base\ModelEvent;
use yii\base\NotSupportedException;
use yii\base\UnknownMethodException;
use yii\db\ActiveRelationInterface;
use yii\db\Expression;
use yii\db\StaleObjectException;
use yii\helpers\Inflector;
use yii\helpers\StringHelper;
use Yii;
/**
* Class ActiveRecord
* ActiveRecord is the base class for classes representing relational data in terms of objects.
*
* @property array $dirtyAttributes The changed attribute values (name-value pairs). This property is
* read-only.
* @property boolean $isNewRecord Whether the record is new and should be inserted when calling [[save()]].
* @property array $oldAttributes The old attribute values (name-value pairs).
* @property integer $oldPrimaryKey The old primary key value. This property is read-only.
* @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.
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
......@@ -148,7 +156,7 @@ class ActiveRecord extends Model
* Below is an example:
*
* ~~~
* $customers = Customer::findBySql('SELECT * FROM tbl_customer')->all();
* $customers = Article::findBySql("SELECT * FROM `idx_article` WHERE MATCH('development')")->all();
* ~~~
*
* @param string $sql the SQL statement to be executed
......@@ -164,10 +172,10 @@ class ActiveRecord extends Model
/**
* Updates the whole table using the provided attribute values and conditions.
* For example, to change the status to be 1 for all customers whose status is 2:
* For example, to change the status to be 1 for all articles which status is 2:
*
* ~~~
* Customer::updateAll(['status' => 1], 'status = 2');
* Article::updateAll(['status' => 1], 'status = 2');
* ~~~
*
* @param array $attributes attribute values (name-value pairs) to be saved into the table
......@@ -184,13 +192,12 @@ class ActiveRecord extends Model
}
/**
* Deletes rows in the table using the provided conditions.
* WARNING: If you do not specify any condition, this method will delete ALL rows in the table.
* Deletes rows in the index using the provided conditions.
*
* For example, to delete all customers whose status is 3:
* For example, to delete all articles whose status is 3:
*
* ~~~
* Customer::deleteAll('status = 3');
* Article::deleteAll('status = 3');
* ~~~
*
* @param string|array $condition the conditions that will be put in the WHERE part of the DELETE SQL.
......@@ -208,8 +215,8 @@ class ActiveRecord extends Model
/**
* Creates an [[ActiveQuery]] instance.
* This method is called by [[find()]], [[findBySql()]] and [[count()]] to start a SELECT query.
* You may override this method to return a customized query (e.g. `CustomerQuery` specified
* written for querying `Customer` purpose.)
* You may override this method to return a customized query (e.g. `ArticleQuery` specified
* written for querying `Article` purpose.)
* @return ActiveQuery the newly created [[ActiveQuery]] instance.
*/
public static function createQuery()
......@@ -218,11 +225,11 @@ class ActiveRecord extends Model
}
/**
* Declares the name of the database table associated with this AR class.
* By default this method returns the class name as the table name by calling [[Inflector::camel2id()]]
* with prefix 'tbl_'. For example, 'Customer' becomes 'tbl_customer', and 'OrderItem' becomes
* 'tbl_order_item'. You may override this method if the table is not named after this convention.
* @return string the table name
* Declares the name of the Sphinx index associated with this AR class.
* By default this method returns the class name as the index name by calling [[Inflector::camel2id()]].
* For example, 'Article' becomes 'article', and 'StockItem' becomes
* 'stock_item'. You may override this method if the index is not named after this convention.
* @return string the index name
*/
public static function indexName()
{
......@@ -230,9 +237,9 @@ class ActiveRecord extends Model
}
/**
* Returns the schema information of the DB table associated with this AR class.
* @return IndexSchema the schema information of the DB table associated with this AR class.
* @throws InvalidConfigException if the table for the AR class does not exist.
* Returns the schema information of the Sphinx index associated with this AR class.
* @return IndexSchema the schema information of the Sphinx index associated with this AR class.
* @throws InvalidConfigException if the index for the AR class does not exist.
*/
public static function getIndexSchema()
{
......@@ -246,7 +253,7 @@ class ActiveRecord extends Model
/**
* Returns the primary key name for this AR class.
* @return string the primary keys of the associated database table.
* @return string the primary key of the associated Sphinx index.
*/
public static function primaryKey()
{
......@@ -257,15 +264,15 @@ class ActiveRecord extends Model
* Builds a snippet from provided data and query, using specified index settings.
* @param string|array $source is the source data to extract a snippet from.
* It could be either a single string or array of strings.
* @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|array built snippet in case "source" is a string, list of built snippets
* in case "source" is an array.
*/
public static function callSnippets($source, $query, $options = [])
public static function callSnippets($source, $match, $options = [])
{
$command = static::getDb()->createCommand();
$command->callSnippets(static::indexName(), $source, $query, $options);
$command->callSnippets(static::indexName(), $source, $match, $options);
if (is_array($source)) {
return $command->queryColumn();
} else {
......
extensions/sphinx/Command.php
......@@ -13,7 +13,37 @@ use yii\caching\Cache;
use yii\db\Exception;
/**
* Class Command
* Command represents a SQL statement to be executed against a Sphinx.
*
* A command object is usually created by calling [[Connection::createCommand()]].
* The SQL statement it represents can be set via the [[sql]] property.
*
* To execute a non-query SQL (such as INSERT, REPLACE, DELETE, UPDATE), call [[execute()]].
* To execute a SQL statement that returns result data set (such as SELECT, CALL SNIPPETS, CALL KEYWORDS),
* use [[queryAll()]], [[queryOne()]], [[queryColumn()]], [[queryScalar()]], or [[query()]].
* For example,
*
* ~~~
* $articles = $connection->createCommand("SELECT * FROM `idx_article` WHERE MATCH('programming')")->queryAll();
* ~~~
*
* Command supports SQL statement preparation and parameter binding just as [[\yii\db\Command]] does.
*
* Command also supports building SQL statements by providing methods such as [[insert()]],
* [[update()]], etc. For example,
*
* ~~~
* $connection->createCommand()->update('idx_article', [
* 'genre_id' => 15,
* 'author_id' => 157,
* ])->execute();
* ~~~
*
* To build SELECT SQL statements, please use [[Query]] and [[QueryBuilder]] instead.
*
* @property string $rawSql The raw SQL with parameter values inserted into the corresponding placeholders in
* [[sql]]. This property is read-only.
* @property string $sql The SQL statement to be executed.
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
......@@ -554,14 +584,14 @@ class Command extends Component
* @param string $index name of the index, from which to take the text processing settings.
* @param string|array $source is the source data to extract a snippet from.
* It could be either a single string or array of strings.
* @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 static the command object itself
*/
public function callSnippets($index, $source, $query, $options = [])
public function callSnippets($index, $source, $match, $options = [])
{
$params = [];
$sql = $this->db->getQueryBuilder()->callSnippets($index, $source, $query, $options, $params);
$sql = $this->db->getQueryBuilder()->callSnippets($index, $source, $match, $options, $params);
return $this->setSql($sql)->bindValues($params);
}
......
extensions/sphinx/Connection.php
......@@ -6,14 +6,51 @@
*/
namespace yii\sphinx;
use yii\base\NotSupportedException;
/**
* Class Connection
* Connection represents the Sphinx connection via MySQL protocol.
* This class uses [PDO](http://www.php.net/manual/en/ref.pdo.php) to maintain such connection.
* 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:
* ~~~
* $connection = new \yii\db\Connection([
* 'dsn' => 'mysql:host=127.0.0.1;port=9306;',
* 'username' => $username,
* 'password' => $password,
* ]);
* $connection->open();
* ~~~
*
* After the Sphinx connection is established, one can execute SQL statements like the following:
* ~~~
* $command = $connection->createCommand("SELECT * FROM idx_article WHERE MATCH('programming')");
* $articles = $command->queryAll();
* $command = $connection->createCommand('UPDATE idx_article SET status=2 WHERE id=1');
* $command->execute();
* ~~~
*
* For more information about how to perform various DB queries, please refer to [[Command]].
*
* This class supports transactions exactly as "yii\db\Connection".
*
* Note: while this class extends "yii\db\Connection" some of its methods are not supported.
*
* @property Schema $schema The schema information for this Sphinx connection. This property is read-only.
* @property \yii\sphinx\QueryBuilder $queryBuilder The query builder for this Sphinx connection. This property is
* read-only.
* @method Schema getSchema() The schema information for this Sphinx connection
* @method \yii\sphinx\Schema getSchema() The schema information for this Sphinx connection
* @method \yii\sphinx\QueryBuilder getQueryBuilder() the query builder for this Sphinx connection
*
* @author Paul Klimov <klimov.paul@gmail.com>
......@@ -78,4 +115,15 @@ class Connection extends \yii\db\Connection
]);
return $command->bindValues($params);
}
/**
* This method is not supported by Sphinx.
* @param string $sequenceName name of the sequence object
* @return string the row ID of the last row inserted, or the last value retrieved from the sequence object
* @throws \yii\base\NotSupportedException always.
*/
public function getLastInsertID($sequenceName = '')
{
throw new NotSupportedException('"' . $this->className() . '::getLastInsertID" is not supported.');
}
}
\ No newline at end of file
extensions/sphinx/QueryBuilder.php
......@@ -12,7 +12,10 @@ use yii\db\Exception;
use yii\db\Expression;
/**
* Class QueryBuilder
* QueryBuilder builds a SELECT SQL statement based on the specification given as a [[Query]] object.
*
* QueryBuilder can also be used to build SQL statements such as INSERT, REPLACE, UPDATE, DELETE,
* from a [[Query]] object.
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
......@@ -22,7 +25,7 @@ class QueryBuilder extends Object
/**
* The prefix for automatically generated query binding parameters.
*/
const PARAM_PREFIX = ':sp';
const PARAM_PREFIX = ':qp';
/**
* @var Connection the Sphinx connection.
......@@ -80,6 +83,7 @@ class QueryBuilder extends Object
* $sql = $queryBuilder->insert('idx_user', [
* 'name' => 'Sam',
* 'age' => 30,
* 'id' => 10,
* ], $params);
* ~~~
*
......@@ -104,6 +108,7 @@ class QueryBuilder extends Object
* $sql = $queryBuilder->replace('idx_user', [
* 'name' => 'Sam',
* 'age' => 30,
* 'id' => 10,
* ], $params);
* ~~~
*
......@@ -151,10 +156,10 @@ class QueryBuilder extends Object
* For example,
*
* ~~~
* $connection->createCommand()->batchInsert('idx_user', ['name', 'age'], [
* ['Tom', 30],
* ['Jane', 20],
* ['Linda', 25],
* $connection->createCommand()->batchInsert('idx_user', ['id', 'name', 'age'], [
* [1, 'Tom', 30],
* [2, 'Jane', 20],
* [3, 'Linda', 25],
* ])->execute();
* ~~~
*
......@@ -164,7 +169,7 @@ class QueryBuilder extends Object
* @param array $columns the column names
* @param array $rows the rows to be batch inserted into the index
* @param array $params the binding parameters that will be generated by this method.
* They should be bound to the DB command later.
* They should be bound to the Sphinx command later.
* @return string the batch INSERT SQL statement
*/
public function batchInsert($index, $columns, $rows, &$params)
......@@ -177,10 +182,10 @@ class QueryBuilder extends Object
* For example,
*
* ~~~
* $connection->createCommand()->batchReplace('idx_user', ['name', 'age'], [
* ['Tom', 30],
* ['Jane', 20],
* ['Linda', 25],
* $connection->createCommand()->batchReplace('idx_user', ['id', 'name', 'age'], [
* [1, 'Tom', 30],
* [2, 'Jane', 20],
* [3, 'Linda', 25],
* ])->execute();
* ~~~
*
......@@ -190,7 +195,7 @@ class QueryBuilder extends Object
* @param array $columns the column names
* @param array $rows the rows to be batch replaced in the index
* @param array $params the binding parameters that will be generated by this method.
* They should be bound to the DB command later.
* They should be bound to the Sphinx command later.
* @return string the batch INSERT SQL statement
*/
public function batchReplace($index, $columns, $rows, &$params)
......@@ -248,7 +253,7 @@ class QueryBuilder extends Object
* @param array|string $condition the condition that will be put in the WHERE part. Please
* refer to [[Query::where()]] on how to specify condition.
* @param array $params the binding parameters that will be modified by this method
* so that they can be bound to the DB command later.
* so that they can be bound to the Sphinx command later.
* @param array $options list of options in format: optionName => optionValue
* @return string the UPDATE SQL
*/
......@@ -282,7 +287,7 @@ class QueryBuilder extends Object
* For example,
*
* ~~~
* $sql = $queryBuilder->delete('tbl_user', 'status = 0');
* $sql = $queryBuilder->delete('idx_user', 'status = 0');
* ~~~
*
* The method will properly escape the index and column names.
......@@ -291,7 +296,7 @@ class QueryBuilder extends Object
* @param array|string $condition the condition that will be put in the WHERE part. Please
* refer to [[Query::where()]] on how to specify condition.
* @param array $params the binding parameters that will be modified by this method
* so that they can be bound to the DB command later.
* so that they can be bound to the Sphinx command later.
* @return string the DELETE SQL
*/
public function delete($index, $condition, &$params)
......@@ -316,13 +321,13 @@ class QueryBuilder extends Object
* @param string $index name of the index, from which to take the text processing settings.
* @param string|array $source is the source data to extract a snippet from.
* It could be either a single string or array of strings.
* @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
* @param array $params the binding parameters that will be modified by this method
* so that they can be bound to the Sphinx command later.
* @return string the SQL statement for call snippets.
*/
public function callSnippets($index, $source, $query, $options, &$params)
public function callSnippets($index, $source, $match, $options, &$params)
{
if (is_array($source)) {
$dataSqlParts = [];
......@@ -339,8 +344,8 @@ class QueryBuilder extends Object
}
$indexParamName = self::PARAM_PREFIX . count($params);
$params[$indexParamName] = $index;
$queryParamName = self::PARAM_PREFIX . count($params);
$params[$queryParamName] = $query;
$matchParamName = self::PARAM_PREFIX . count($params);
$params[$matchParamName] = $match;
if (!empty($options)) {
$optionParts = [];
foreach ($options as $name => $value) {
......@@ -356,7 +361,7 @@ class QueryBuilder extends Object
} else {
$optionSql = '';
}
return 'CALL SNIPPETS(' . $dataSql. ', ' . $indexParamName . ', ' . $queryParamName . $optionSql. ')';
return 'CALL SNIPPETS(' . $dataSql. ', ' . $indexParamName . ', ' . $matchParamName . $optionSql. ')';
}
/**
......
extensions/sphinx/README.md
......@@ -39,4 +39,15 @@ Usage & Documentation
This extension adds [Sphinx](http://sphinxsearch.com/docs) full text search engine extension for the Yii framework.
This extension interact with Sphinx search daemon using MySQL protocol and [SphinxQL](http://sphinxsearch.com/docs/current.html#sphinxql) query language.
In order to setup Sphinx "searchd" to support MySQL protocol following configuration should be added:
```
searchd
{
listen = localhost:9306:mysql41
...
}
```
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
extensions/sphinx/Schema.php
......@@ -15,6 +15,13 @@ use yii\caching\GroupDependency;
/**
* Schema represents the Sphinx schema information.
*
* @property QueryBuilder $queryBuilder The query builder for this connection. This property is read-only.
* @property string[] $indexNames All index names in the Sphinx. This property is read-only.
* @property string[] $indexTypes ALL index types in the Sphinx (index name => index type).
* This property is read-only.
* @property IndexSchema[] $tableSchemas The metadata for all indexes in the Sphinx. Each array element is an
* instance of [[IndexSchema]] or its child class. This property is read-only.
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
*/
......
extensions/sphinx/composer.json
......@@ -19,7 +19,9 @@
],
"minimum-stability": "dev",
"require": {
"yiisoft/yii2": "*"
"yiisoft/yii2": "*",
"ext-pdo": "*",
"ext-pdo_mysql": "*"
},
"autoload": {
"psr-0": { "yii\\sphinx\\": "" }
......
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