diff --git a/framework/db/ActiveRelationTrait.php b/framework/db/ActiveRelationTrait.php index 3dfba4c455..ffcbe238da 100644 --- a/framework/db/ActiveRelationTrait.php +++ b/framework/db/ActiveRelationTrait.php @@ -114,13 +114,12 @@ trait ActiveRelationTrait /** * Sets the name of the relation that is the inverse of this relation. - * For example, an order has a customer, which means the inverse of the "customer" relation - * is the "orders", and the inverse of the "orders" relation is the "customer". + * For example, a customer has orders, which means the inverse of the "orders" relation is the "customer". * If this property is set, the primary record(s) will be referenced through the specified relation. * For example, `$customer->orders[0]->customer` and `$customer` will be the same object, * and accessing the customer of an order will not trigger a new DB query. * - * Use this method when declaring a relation in the [[ActiveRecord]] class: + * Use this method when declaring a relation in the [[ActiveRecord]] class, e.g. in Customer model: * * ```php * public function getOrders() @@ -129,6 +128,32 @@ trait ActiveRelationTrait * } * ``` * + * This also may be used for Order model, but with caution: + * + * ```php + * public function getCustomer() + * { + * return $this->hasOne(Customer::className(), ['id' => 'customer_id'])->inverseOf('orders'); + * } + * ``` + * + * in this case result will depend on how order(s) was loaded. + * Let's suppose customer has several orders. If only one order was loaded: + * + * ```php + * $orders = Order::find()->where(['id' => 1])->all(); + * $customerOrders = $orders[0]->customer->orders; + * ``` + * + * variable `$customerOrders` will contain only one order. If orders was loaded like this: + * + * ```php + * $orders = Order::find()->with('customer')->where(['customer_id' => 1])->all(); + * $customerOrders = $orders[0]->customer->orders; + * ``` + * + * variable `$customerOrders` will contain all orders of the customer. + * * @param string $relationName the name of the relation that is the inverse of this relation. * @return $this the relation object itself. */