Fixes #58: Add a getByName method to the Sites action. (#60)

* Issue #58: Add a getByName method to the Sites action.

* Issue #58: Add missing return value description.

* Issue #58: Add code coverage for Sites changes.

* Issue #58: Add missing comma for Travis.

* Issue #58: Correct @Covers statement.

Author: swichers

src/Endpoints/Action/Sites.php

@@ -2,7 +2,9 @@
 
 namespace swichers\Acsf\Client\Endpoints\Action;
 
+use swichers\Acsf\Client\Endpoints\Entity\EntityInterface;
 use swichers\Acsf\Client\Endpoints\ValidationTrait;
+use swichers\Acsf\Client\Exceptions\MissingEntityException;
 
 /**
  * ACSF Endpoint Wrapper: Sites.
@@ -260,7 +262,7 @@ public function listAll() : array {
       ];
 
       $site_info = $this->list($options);
-      $sites['sites'] = array_merge($sites['sites'], $site_info['sites'] ?: []);
+      $sites['sites'] = array_merge($sites['sites'], $site_info['sites'] ?? []);
 
       $has_more =
         !empty($site_info['count']) &&
@@ -293,4 +295,27 @@ public function getAll() : array {
     return $sites ?: [];
   }
 
+  /**
+   * Get a Site by its human name instead of ID.
+   *
+   * @param string $name
+   *   The human name of a site factory site.
+   *
+   * @return \swichers\Acsf\Client\Endpoints\Entity\EntityInterface
+   *   The site that matches the given name.
+   *
+   * @throws \swichers\Acsf\Client\Exceptions\MissingEntityException
+   */
+  public function getByName(string $name) : EntityInterface {
+
+    $sites_list = $this->listAll()['sites'] ?? [];
+    foreach ($sites_list as $info) {
+      if ($info['site'] == $name) {
+        return $this->get($info['id']);
+      }
+    }
+
+    throw new MissingEntityException(sprintf('Unable to load Site with the name %s.', $name));
+  }
+
 }

tests/Unit/ClientTest.php

@@ -503,7 +503,7 @@ public function testGetEntityFailId() {
   /**
    * {@inheritdoc}
    */
-  protected function setUp() {
+  protected function setUp() : void {
 
     parent::setUp();
 

tests/Unit/Discovery/ManagerTest.php

@@ -92,7 +92,7 @@ public function testGet() {
   /**
    * {@inheritdoc}
    */
-  protected function setUp() {
+  protected function setUp() : void {
 
     parent::setUp();
 

tests/Unit/Endpoints/Action/AbstractActionTestBase.php

@@ -18,7 +18,7 @@ abstract class AbstractActionTestBase extends TestCase {
   /**
    * {@inheritdoc}
    */
-  protected function setUp() {
+  protected function setUp() : void {
 
     parent::setUp();
 

tests/Unit/Endpoints/Action/AbstractEntityActionTest.php

@@ -58,7 +58,7 @@ public function testGetFail() {
   /**
    * {@inheritdoc}
    */
-  protected function setUp() {
+  protected function setUp() : void {
 
     parent::setUp();
 

tests/Unit/Endpoints/Action/SitesTest.php

@@ -3,6 +3,9 @@
 namespace swichers\Acsf\Client\Tests\Endpoints\Action;
 
 use swichers\Acsf\Client\Endpoints\Action\Sites;
+use swichers\Acsf\Client\Endpoints\Entity\EntityInterface;
+use swichers\Acsf\Client\Endpoints\Entity\Site;
+use swichers\Acsf\Client\Exceptions\MissingEntityException;
 
 /**
  * Tests for the SitesTest Action.
@@ -74,4 +77,80 @@ public function testGetEntityType() {
     $this->assertSame('Site', $action->getEntityType());
   }
 
+  /**
+   * Validates we can get a list of all Sites despite pagination.
+   *
+   * @covers ::listAll
+   */
+  public function testListAll() {
+
+    $action = $this->getMockBuilder(Sites::class)
+      ->setConstructorArgs([$this->mockClient])
+      ->setMethods(['list'])
+      ->getMock();
+    $action->method('list')->willReturnCallback(function ($options) {
+      $page = $options['page'] ?: 1;
+
+      if ($page == 1) {
+        $sites = range(1, 10);
+      }
+      elseif ($page == 2) {
+        $sites = range(1, 5);
+      }
+
+      return ['sites' => $sites ?: [], 'count' => 15];
+    });
+
+    $list = $action->listAll();
+    $this->assertArrayHasKey('sites', $list);
+    $this->assertArrayHasKey('count', $list);
+    $this->assertCount(15, $list['sites']);
+    $this->assertEquals(15, $list['count']);
+  }
+
+  /**
+   * Validates we can get a Site by its name.
+   *
+   * @covers ::getByName
+   */
+  public function testGetByName() {
+
+    $action = $this->getMockBuilder(Sites::class)
+      ->setConstructorArgs([$this->mockClient])
+      ->setMethods(['listAll', 'get'])
+      ->getMock();
+
+    $action->method('get')->willReturnMap([
+      [123, new Site($this->mockClient, 123)],
+    ]);
+
+    $action->method('listAll')->willReturn([
+      'sites' => [
+        [
+          'site' => 'UnitTest',
+          'id' => 123,
+        ],
+      ],
+    ]);
+
+    /** @var \swichers\Acsf\Client\Endpoints\Entity\Site $site */
+    $site = $action->getByName('UnitTest');
+    $this->assertInstanceOf(EntityInterface::class, $site);
+    $this->assertEquals(123, $site->id());
+  }
+
+  /**
+   * Validate we get a MissingEntityException if a bad name is given.
+   *
+   * @covers ::getByName
+   *
+   * @depends testGetByName
+   */
+  public function testGetByNameMissing() {
+
+    $action = new Sites($this->getMockAcsfClient());
+    $this->expectException(MissingEntityException::class);
+    $action->getByName('No site');
+  }
+
 }