[9.x] Add ability to define "with" relations as a nested array (#42690)

* Add ability to define "with" relations as a nested array.

* typo

* formatting

Co-authored-by: Taylor Otwell <[email protected]>

Author: timacdonald

src/Illuminate/Database/Eloquent/Builder.php

@@ -1430,22 +1430,13 @@ public function newModelInstance($attributes = [])
      */
     protected function parseWithRelations(array $relations)
     {
-        $results = [];
+        if ($relations === []) {
+            return [];
+        }
 
-        foreach ($relations as $name => $constraints) {
-            // If the "name" value is a numeric key, we can assume that no constraints
-            // have been specified. We will just put an empty Closure there so that
-            // we can treat these all the same while we are looping through them.
-            if (is_numeric($name)) {
-                $name = $constraints;
-
-                [$name, $constraints] = str_contains($name, ':')
-                            ? $this->createSelectWithConstraint($name)
-                            : [$name, static function () {
-                                //
-                            }];
-            }
+        $results = [];
 
+        foreach ($this->prepareNestedWithRelationships($relations) as $name => $constraints) {
             // We need to separate out any nested includes, which allows the developers
             // to load deep relationships using "dots" without stating each level of
             // the relationship with its own key in the array of eager-load names.
@@ -1457,6 +1448,91 @@ protected function parseWithRelations(array $relations)
         return $results;
     }
 
+    /**
+     * Prepare nested with relationships.
+     *
+     * @param  array  $relations
+     * @param  string  $prefix
+     * @return array
+     */
+    protected function prepareNestedWithRelationships($relations, $prefix = '')
+    {
+        $preparedRelationships = [];
+
+        if ($prefix !== '') {
+            $prefix .= '.';
+        }
+
+        // If any of the relationships are formatted with the [$attribute => array()]
+        // syntax, we shall loop over the nested relations and prepend each key of
+        // this array while flattening into the traditional dot notation format.
+        foreach ($relations as $key => $value) {
+            if (! is_string($key) || ! is_array($value)) {
+                continue;
+            }
+
+            [$attribute, $attributeSelectConstraint] = $this->parseNameAndAttributeSelectionConstraint($key);
+
+            $preparedRelationships = array_merge(
+                $preparedRelationships,
+                ["{$prefix}{$attribute}" => $attributeSelectConstraint],
+                $this->prepareNestedWithRelationships($value, "{$prefix}{$attribute}"),
+            );
+
+            unset($relations[$key]);
+        }
+
+        // We now know that the remaining relationships are in a dot notation format
+        // and may be a string or Closure. We'll loop over them and ensure all of
+        // the present Closures are merged + strings are made into constraints.
+        foreach ($relations as $key => $value) {
+            if (is_numeric($key) && is_string($value)) {
+                [$key, $value] = $this->parseNameAndAttributeSelectionConstraint($value);
+            }
+
+            $preparedRelationships[$prefix.$key] = $this->combineConstraints([
+                $value,
+                $preparedRelationships[$prefix.$key] ?? static function () {
+                    //
+                },
+            ]);
+        }
+
+        return $preparedRelationships;
+    }
+
+    /**
+     * Combine an array of constraints into a single constraint.
+     *
+     * @param  array  $constraints
+     * @return \Closure
+     */
+    protected function combineConstraints(array $constraints)
+    {
+        return function ($builder) use ($constraints) {
+            foreach ($constraints as $constraint) {
+                $builder = $constraint($builder) ?? $builder;
+            }
+
+            return $builder;
+        };
+    }
+
+    /**
+     * Parse the attribute select constraints from the name.
+     *
+     * @param  string  $name
+     * @return array
+     */
+    protected function parseNameAndAttributeSelectionConstraint($name)
+    {
+        return str_contains($name, ':')
+            ? $this->createSelectWithConstraint($name)
+            : [$name, static function () {
+                //
+            }];
+    }
+
     /**
      * Create a constraint to select the given columns for the relation.
      *

tests/Database/DatabaseEloquentBuilderTest.php

@@ -842,7 +842,7 @@ public function testEagerLoadParsingSetsProperRelationships()
         }]);
         $eagers = $builder->getEagerLoads();
 
-        $this->assertSame('foo', $eagers['orders']());
+        $this->assertSame('foo', $eagers['orders']($this->getBuilder()));
 
         $builder = $this->getBuilder();
         $builder->with(['orders.lines' => function () {
@@ -852,7 +852,7 @@ public function testEagerLoadParsingSetsProperRelationships()
 
         $this->assertInstanceOf(Closure::class, $eagers['orders']);
         $this->assertNull($eagers['orders']());
-        $this->assertSame('foo', $eagers['orders.lines']());
+        $this->assertSame('foo', $eagers['orders.lines']($this->getBuilder()));
 
         $builder = $this->getBuilder();
         $builder->with('orders.lines', function () {
@@ -862,7 +862,7 @@ public function testEagerLoadParsingSetsProperRelationships()
 
         $this->assertInstanceOf(Closure::class, $eagers['orders']);
         $this->assertNull($eagers['orders']());
-        $this->assertSame('foo', $eagers['orders.lines']());
+        $this->assertSame('foo', $eagers['orders.lines']($this->getBuilder()));
     }
 
     public function testQueryPassThru()