Add `AssociationCollection::load` method.

src/ORM/AssociationCollection.php

@@ -57,6 +57,30 @@ class AssociationCollection implements IteratorAggregate
     }
 
     /**
+     * Creates and adds the Association object to this collection.
+     *
+     * @param string $className The name of association class.
+     * @param string $associated The alias for the target table.
+     * @param array $options List of options to configure the association definition.
+     * @return \Cake\ORM\Association
+     * @throws InvalidArgumentException
+     */
+    public function load($className, $associated, array $options = [])
+    {
+        $options += [
+            'tableLocator' => $this->getTableLocator()
+        ];
+
+        $association = new $className($associated, $options);
+        if (!$association instanceof Association) {
+            $message = sprintf('The association must extend `%s` class, `%s` given.', Association::class, get_class($association));
+            throw new InvalidArgumentException($message);
+        }
+
+        return $this->add($association->getName(), $association);
+    }
+
+    /**
      * Fetch an attached association by name.
      *
      * @param string $alias The association alias to get.

tests/TestCase/ORM/AssociationCollectionTest.php

@@ -18,6 +18,7 @@ use Cake\ORM\AssociationCollection;
 use Cake\ORM\Association\BelongsTo;
 use Cake\ORM\Association\BelongsToMany;
 use Cake\ORM\Entity;
+use Cake\ORM\Locator\LocatorInterface;
 use Cake\TestSuite\TestCase;
 
 /**
@@ -71,6 +72,47 @@ class AssociationCollectionTest extends TestCase
     }
 
     /**
+     * Test the load method.
+     *
+     * @return void
+     */
+    public function testLoad()
+    {
+        $this->associations->load(BelongsTo::class, 'Users');
+        $this->assertTrue($this->associations->has('Users'));
+        $this->assertInstanceOf(BelongsTo::class, $this->associations->get('Users'));
+        $this->assertSame($this->associations->getTableLocator(), $this->associations->get('Users')->getTableLocator());
+    }
+
+    /**
+     * Test the load method with custom locator.
+     *
+     * @return void
+     */
+    public function testLoadCustomLocator()
+    {
+        $locator = $this->createMock(LocatorInterface::class);
+        $this->associations->load(BelongsTo::class, 'Users', [
+            'tableLocator' => $locator
+        ]);
+        $this->assertTrue($this->associations->has('Users'));
+        $this->assertInstanceOf(BelongsTo::class, $this->associations->get('Users'));
+        $this->assertSame($locator, $this->associations->get('Users')->getTableLocator());
+    }
+
+    /**
+     * Test load invalid class.
+     *
+     * @return void
+     * @expectedException InvalidArgumentException
+     * @expectedExceptionMessage The association must extend `Cake\ORM\Association` class, `stdClass` given.
+     */
+    public function testLoadInvalid()
+    {
+        $this->associations->load('stdClass', 'Users');
+    }
+
+    /**
      * Test removeAll method
      *
      * @return void