Fixes #7316: Documentation for ActiveRelationTrait::inverseOf() [skip ci] (#14892)

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
+     * For example, a customer has orders, which means the inverse of the "orders" relation is the "customer".
-     * is the "orders", and 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.
      */