Sphinx documentation updated.

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\\": "" }