ActiveRelation.php 4.3 KB
Newer Older
Qiang Xue committed
1
<?php
Qiang Xue committed
2 3 4
/**
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.yiiframework.com/
Qiang Xue committed
5
 * @copyright Copyright (c) 2008 Yii Software LLC
Qiang Xue committed
6 7
 * @license http://www.yiiframework.com/license/
 */
Qiang Xue committed
8

Qiang Xue committed
9
namespace yii\db;
Qiang Xue committed
10

Qiang Xue committed
11
/**
Qiang Xue committed
12 13 14 15 16 17 18 19 20 21
 * ActiveRelation represents a relation between two Active Record classes.
 *
 * ActiveRelation instances are usually created by calling [[ActiveRecord::hasOne()]] and
 * [[ActiveRecord::hasMany()]]. An Active Record class declares a relation by defining
 * a getter method which calls one of the above methods and returns the created ActiveRelation object.
 *
 * 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.
Qiang Xue committed
22 23
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
24
 * @author Carsten Brandt <mail@cebe.cc>
Qiang Xue committed
25 26
 * @since 2.0
 */
27
class ActiveRelation extends ActiveQuery implements ActiveRelationInterface
Qiang Xue committed
28
{
29
	use ActiveRelationTrait;
Qiang Xue committed
30

31 32
	/**
	 * @var string|array the join condition. Please refer to [[Query::where()]] on how to specify this parameter.
33
	 * The condition will be used in the ON part when [[ActiveQuery::joinWith()]] is called.
34 35 36 37 38 39
	 * Otherwise, the condition will be used in the WHERE part of a query.
	 */
	public $on;

	/**
	 * Sets the ON condition for the query.
40
	 * The condition will be used in the ON part when [[ActiveQuery::joinWith()]] is called.
41 42 43 44 45 46 47 48 49 50 51 52
	 * Otherwise, the condition will be used in the WHERE part of a query.
	 * @param string|array $condition the ON condition. Please refer to [[Query::where()]] on how to specify this parameter.
	 * @param array $params the parameters (name => value) to be bound to the query.
	 * @return static the query object itself
	 */
	public function onCondition($condition, $params = [])
	{
		$this->on = $condition;
		$this->addParams($params);
		return $this;
	}

Qiang Xue committed
53
	/**
Qiang Xue committed
54 55 56 57 58
	 * Specifies the pivot table.
	 * @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
	 * in the [[primaryModel]] table.
Qiang Xue committed
59
	 * @param callable $callable a PHP callback for customizing the relation associated with the pivot table.
Qiang Xue committed
60
	 * Its signature should be `function($query)`, where `$query` is the query to be customized.
61
	 * @return static
Qiang Xue committed
62
	 */
Qiang Xue committed
63
	public function viaTable($tableName, $link, $callable = null)
Qiang Xue committed
64
	{
Alexander Makarov committed
65
		$relation = new ActiveRelation([
Qiang Xue committed
66
			'modelClass' => get_class($this->primaryModel),
Alexander Makarov committed
67
			'from' => [$tableName],
Qiang Xue committed
68 69 70
			'link' => $link,
			'multiple' => true,
			'asArray' => true,
Alexander Makarov committed
71
		]);
Qiang Xue committed
72
		$this->via = $relation;
Qiang Xue committed
73 74
		if ($callable !== null) {
			call_user_func($callable, $relation);
Qiang Xue committed
75
		}
Qiang Xue committed
76 77
		return $this;
	}
Qiang Xue committed
78

Qiang Xue committed
79 80
	/**
	 * Creates a DB command that can be used to execute this query.
Qiang Xue committed
81 82
	 * @param Connection $db the DB connection used to create the DB command.
	 * If null, the DB connection returned by [[modelClass]] will be used.
Qiang Xue committed
83 84
	 * @return Command the created DB command instance.
	 */
Qiang Xue committed
85
	public function createCommand($db = null)
Qiang Xue committed
86
	{
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
		if ($this->primaryModel === null) {
			// eager loading
			if (!empty($this->on)) {
				$where = $this->where;
				$this->andWhere($this->on);
				$command = parent::createCommand($db);
				$this->where = $where;
				return $command;
			} else {
				return parent::createCommand($db);
			}
		}

		// lazy loading

		$where = $this->where;

		if ($this->via instanceof self) {
			// via pivot table
			$viaModels = $this->via->findPivotRows([$this->primaryModel]);
			$this->filterByModels($viaModels);
		} elseif (is_array($this->via)) {
			// via relation
			/** @var ActiveRelation $viaQuery */
			list($viaName, $viaQuery) = $this->via;
			if ($viaQuery->multiple) {
				$viaModels = $viaQuery->all();
				$this->primaryModel->populateRelation($viaName, $viaModels);
115
			} else {
116 117 118
				$model = $viaQuery->one();
				$this->primaryModel->populateRelation($viaName, $model);
				$viaModels = $model === null ? [] : [$model];
119
			}
120 121 122
			$this->filterByModels($viaModels);
		} else {
			$this->filterByModels([$this->primaryModel]);
Qiang Xue committed
123
		}
124 125 126 127 128 129 130 131 132 133

		if (!empty($this->on)) {
			$this->andWhere($this->on);
		}

		$command = parent::createCommand($db);

		$this->where = $where;

		return $command;
Qiang Xue committed
134
	}
Qiang Xue committed
135
}