Commit cba52e3c by Alexander Makarov

Fixes #5382: renamed "pivot table" to "junction table" since it's correct term to use

parent 73dd269e
......@@ -465,14 +465,14 @@ an `ActiveQuery` instance, while `$customer->orders` returns an array of `Order`
the query results in nothing).
Relations with Pivot Table
--------------------------
Relations with Junction Table
-----------------------------
Sometimes, two tables are related together via an intermediary table called [pivot table][]. To declare such relations,
Sometimes, two tables are related together via an intermediary table called [junction table][]. To declare such relations,
we can customize the [[yii\db\ActiveQuery]] object by calling its [[yii\db\ActiveQuery::via()|via()]] or
[[yii\db\ActiveQuery::viaTable()|viaTable()]] method.
For example, if table `order` and table `item` are related via pivot table `order_item`,
For example, if table `order` and table `item` are related via junction table `order_item`,
we can declare the `items` relation in the `Order` class like the following:
```php
......@@ -488,7 +488,7 @@ class Order extends \yii\db\ActiveRecord
The [[yii\db\ActiveQuery::via()|via()]] method is similar to [[yii\db\ActiveQuery::viaTable()|viaTable()]] except that
the first parameter of [[yii\db\ActiveQuery::via()|via()]] takes a relation name declared in the ActiveRecord class
instead of the pivot table name. For example, the above `items` relation can be equivalently declared as follows:
instead of the junction table name. For example, the above `items` relation can be equivalently declared as follows:
```php
class Order extends \yii\db\ActiveRecord
......@@ -506,7 +506,7 @@ class Order extends \yii\db\ActiveRecord
}
```
[pivot table]: http://en.wikipedia.org/wiki/Pivot_table "Pivot table on Wikipedia"
[junction table]: https://en.wikipedia.org/wiki/Junction_table "Junction table on Wikipedia"
Lazy and Eager Loading
......@@ -561,7 +561,7 @@ As you can see, only two SQL queries are needed for the same task!
> Info: In general, if you are eager loading `N` relations among which `M` relations are defined with `via()` or `viaTable()`,
> a total number of `1+M+N` SQL queries will be performed: one query to bring back the rows for the primary table, one for
> each of the `M` pivot tables corresponding to the `via()` or `viaTable()` calls, and one for each of the `N` related tables.
> each of the `M` junction tables corresponding to the `via()` or `viaTable()` calls, and one for each of the `N` related tables.
> Note: When you are customizing `select()` with eager loading, make sure you include the columns that link
> the related models. Otherwise, the related models will not be loaded. For example,
......
......@@ -60,7 +60,7 @@ use yii\db\ActiveRelationTrait;
* A relation is specified by [[link]] which represents the association between columns
* of different tables; and the multiplicity of the relation is indicated by [[multiple]].
*
* If a relation involves a pivot table, it may be specified by [[via()]].
* If a relation involves a junction table, it may be specified by [[via()]].
* This methods may only be called in a relational context. Same is true for [[inverseOf()]], which
* marks a relation as inverse of another relation.
*
......
......@@ -388,12 +388,12 @@ class Generator extends \yii\gii\Generator
}
/**
* Checks if the given table is a pivot table.
* Checks if the given table is a junction table.
* For simplicity, this method only deals with the case where the pivot contains two PK columns,
* each referencing a column in a different table.
* @param \yii\db\TableSchema the table being checked
* @return array|boolean the relevant foreign key constraint information if the table is a pivot table,
* or false if the table is not a pivot table.
* @return array|boolean the relevant foreign key constraint information if the table is a junction table,
* or false if the table is not a junction table.
*/
protected function checkPivotTable($table)
{
......
......@@ -50,7 +50,7 @@ use yii\db\ActiveRelationTrait;
* A relation is specified by [[link]] which represents the association between columns
* of different tables; and the multiplicity of the relation is indicated by [[multiple]].
*
* If a relation involves a pivot table, it may be specified by [[via()]].
* If a relation involves a junction table, it may be specified by [[via()]].
* This methods may only be called in a relational context. Same is true for [[inverseOf()]], which
* marks a relation as inverse of another relation.
*
......@@ -102,7 +102,7 @@ class ActiveQuery extends Query implements ActiveQueryInterface
// lazy loading
if ($this->via instanceof self) {
// via pivot collection
$viaModels = $this->via->findPivotRows([$this->primaryModel]);
$viaModels = $this->via->findJunctionRows([$this->primaryModel]);
$this->filterByModels($viaModels);
} elseif (is_array($this->via)) {
// via relation
......
......@@ -64,7 +64,7 @@ use yii\db\QueryTrait;
* A relation is specified by [[link]] which represents the association between columns
* of different tables; and the multiplicity of the relation is indicated by [[multiple]].
*
* If a relation involves a pivot table, it may be specified by [[via()]].
* If a relation involves a junction table, it may be specified by [[via()]].
* This methods may only be called in a relational context. Same is true for [[inverseOf()]], which
* marks a relation as inverse of another relation.
*
......@@ -312,8 +312,8 @@ class ActiveQuery extends Component implements ActiveQueryInterface
if ($this->primaryModel !== null) {
// lazy loading
if ($this->via instanceof self) {
// via pivot table
$viaModels = $this->via->findPivotRows([$this->primaryModel]);
// via junction table
$viaModels = $this->via->findJunctionRows([$this->primaryModel]);
$this->filterByModels($viaModels);
} elseif (is_array($this->via)) {
// via relation
......
......@@ -73,7 +73,7 @@ use yii\db\ActiveRelationTrait;
* A relation is specified by [[link]] which represents the association between columns
* of different tables; and the multiplicity of the relation is indicated by [[multiple]].
*
* If a relation involves a pivot table, it may be specified by [[via()]].
* If a relation involves a junction table, it may be specified by [[via()]].
* This methods may only be called in a relational context. Same is true for [[inverseOf()]], which
* marks a relation as inverse of another relation.
*
......@@ -225,7 +225,7 @@ class ActiveQuery extends Query implements ActiveQueryInterface
// lazy loading a relational query
if ($this->via instanceof self) {
// via pivot index
$viaModels = $this->via->findPivotRows([$this->primaryModel]);
$viaModels = $this->via->findJunctionRows([$this->primaryModel]);
$this->filterByModels($viaModels);
} elseif (is_array($this->via)) {
// via relation
......
......@@ -58,7 +58,7 @@ namespace yii\db;
* A relation is specified by [[link]] which represents the association between columns
* of different tables; and the multiplicity of the relation is indicated by [[multiple]].
*
* If a relation involves a pivot table, it may be specified by [[via()]] or [[viaTable()]] method.
* If a relation involves a junction table, it may be specified by [[via()]] or [[viaTable()]] method.
* These methods may only be called in a relational context. Same is true for [[inverseOf()]], which
* marks a relation as inverse of another relation and [[onCondition()]] which adds a condition that
* is to be added to relational query join condition.
......@@ -175,8 +175,8 @@ class ActiveQuery extends Query implements ActiveQueryInterface
$where = $this->where;
if ($this->via instanceof self) {
// via pivot table
$viaModels = $this->via->findPivotRows([$this->primaryModel]);
// via junction table
$viaModels = $this->via->findJunctionRows([$this->primaryModel]);
$this->filterByModels($viaModels);
} elseif (is_array($this->via)) {
// via relation
......@@ -655,9 +655,9 @@ class ActiveQuery extends Query implements ActiveQueryInterface
}
/**
* Specifies the pivot table for a relational query.
* Specifies the junction table for a relational query.
*
* Use this method to specify a pivot table when declaring a relation in the [[ActiveRecord]] class:
* Use this method to specify a junction table when declaring a relation in the [[ActiveRecord]] class:
*
* ```php
* public function getItems()
......@@ -667,11 +667,11 @@ class ActiveQuery extends Query implements ActiveQueryInterface
* }
* ```
*
* @param string $tableName the name of the pivot table.
* @param array $link the link between the pivot table and the table associated with [[primaryModel]].
* The keys of the array represent the columns in the pivot table, and the values represent the columns
* @param string $tableName the name of the junction table.
* @param array $link the link between the junction table and the table associated with [[primaryModel]].
* The keys of the array represent the columns in the junction table, and the values represent the columns
* in the [[primaryModel]] table.
* @param callable $callable a PHP callback for customizing the relation associated with the pivot table.
* @param callable $callable a PHP callback for customizing the relation associated with the junction table.
* Its signature should be `function($query)`, where `$query` is the query to be customized.
* @return static
* @see via()
......
......@@ -80,9 +80,9 @@ interface ActiveQueryInterface extends QueryInterface
public function with();
/**
* Specifies the relation associated with the pivot table for use in relational query.
* Specifies the relation associated with the junction table for use in relational query.
* @param string $relationName the relation name. This refers to a relation declared in the [[ActiveRelationTrait::primaryModel|primaryModel]] of the relation.
* @param callable $callable a PHP callback for customizing the relation associated with the pivot table.
* @param callable $callable a PHP callback for customizing the relation associated with the junction table.
* Its signature should be `function($query)`, where `$query` is the query to be customized.
* @return static the relation object itself.
*/
......
......@@ -365,15 +365,15 @@ interface ActiveRecordInterface
* to be the corresponding primary key value(s) in the other record.
* The record with the foreign key will be saved into database without performing validation.
*
* If the relationship involves a pivot table, a new row will be inserted into the
* pivot table which contains the primary key values from both records.
* If the relationship involves a junction table, a new row will be inserted into the
* junction table which contains the primary key values from both records.
*
* This method requires that the primary key value is not null.
*
* @param string $name the case sensitive name of the relationship.
* @param static $model the record to be linked with the current one.
* @param array $extraColumns additional column values to be saved into the pivot table.
* This parameter is only meaningful for a relationship involving a pivot table
* @param array $extraColumns additional column values to be saved into the junction table.
* This parameter is only meaningful for a relationship involving a junction table
* (i.e., a relation set with `[[ActiveQueryInterface::via()]]`.)
*/
public function link($name, $model, $extraColumns = []);
......
......@@ -44,7 +44,7 @@ trait ActiveRelationTrait
*/
public $link;
/**
* @var array|object the query associated with the pivot table. Please call [[via()]]
* @var array|object the query associated with the junction table. Please call [[via()]]
* to set this property instead of directly setting it.
* This property is only used in relational context.
* @see via()
......@@ -78,7 +78,7 @@ trait ActiveRelationTrait
}
/**
* Specifies the relation associated with the pivot table.
* Specifies the relation associated with the junction table.
*
* Use this method to specify a pivot record/table when declaring a relation in the [[ActiveRecord]] class:
*
......@@ -96,7 +96,7 @@ trait ActiveRelationTrait
* ```
*
* @param string $relationName the relation name. This refers to a relation declared in [[primaryModel]].
* @param callable $callable a PHP callback for customizing the relation associated with the pivot table.
* @param callable $callable a PHP callback for customizing the relation associated with the junction table.
* Its signature should be `function($query)`, where `$query` is the query to be customized.
* @return static the relation object itself.
*/
......@@ -195,10 +195,10 @@ trait ActiveRelationTrait
}
if ($this->via instanceof self) {
// via pivot table
// via junction table
/* @var $viaQuery ActiveRelationTrait */
$viaQuery = $this->via;
$viaModels = $viaQuery->findPivotRows($primaryModels);
$viaModels = $viaQuery->findJunctionRows($primaryModels);
$this->filterByModels($viaModels);
} elseif (is_array($this->via)) {
// via relation
......@@ -490,7 +490,7 @@ trait ActiveRelationTrait
* @param array $primaryModels either array of AR instances or arrays
* @return array
*/
private function findPivotRows($primaryModels)
private function findJunctionRows($primaryModels)
{
if (empty($primaryModels)) {
return [];
......
......@@ -1138,15 +1138,15 @@ abstract class BaseActiveRecord extends Model implements ActiveRecordInterface
* to be the corresponding primary key value(s) in the other model.
* The model with the foreign key will be saved into database without performing validation.
*
* If the relationship involves a pivot table, a new row will be inserted into the
* pivot table which contains the primary key values from both models.
* If the relationship involves a junction table, a new row will be inserted into the
* junction table which contains the primary key values from both models.
*
* Note that this method requires that the primary key value is not null.
*
* @param string $name the case sensitive name of the relationship
* @param ActiveRecordInterface $model the model to be linked with the current one.
* @param array $extraColumns additional column values to be saved into the pivot table.
* This parameter is only meaningful for a relationship involving a pivot table
* @param array $extraColumns additional column values to be saved into the junction table.
* This parameter is only meaningful for a relationship involving a junction table
* (i.e., a relation set with [[ActiveRelationTrait::via()]] or `[[ActiveQuery::viaTable()]]`.)
* @throws InvalidCallException if the method is unable to link two models.
*/
......
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