Library extension (#44)

* Extended the functionality of the library in order to support lookup by name identifier.

* Composer update and php-cs-fixer update.

* phpunit tests and corrections

* Updated the docs.

* Changed the name of GB to the initial one. Removed the extra whitespace. Changed the order of the class constants as well as the order in the keys array.

* Removed .idea from the project .gitignore and added it to the global.

.gitignore

@@ -3,4 +3,4 @@
 /.php_cs
 /.php_cs.cache
 /composer.lock
-/phpunit.xml
+/phpunit.xml

docs/using.md

@@ -10,6 +10,12 @@ title: Using league/iso3166
 
 The following methods are provided by the `League\ISO3166\ISO3166DataProvider` interface.
 
+**Lookup data by name:**
+
+``` php
+$data = (new League\ISO3166\ISO3166)->name($name);
+```
+
 **Lookup data by alpha2 code:**
 
 ``` php

src/Guards.php

@@ -14,6 +14,22 @@
 
 final class Guards
 {
+    /**
+     * Assert that input looks like a name key.
+     *
+     * @param string $name
+     *
+     * @throws \League\ISO3166\Exception\InvalidArgumentException if input is not a string
+     */
+    public static function guardAgainstInvalidName($name)
+    {
+        if (!is_string($name)) {
+            throw new InvalidArgumentException(
+                sprintf('Expected $name to be of type string, got: %s', gettype($name))
+            );
+        }
+    }
+
     /**
      * Assert that input looks like an alpha2 key.
      *

src/ISO3166.php

@@ -26,10 +26,14 @@ final class ISO3166 implements \Countable, \IteratorAggregate, ISO3166DataProvid
      * @var string
      */
     const KEY_NUMERIC = 'numeric';
+    /**
+     * @var string
+     */
+    const KEY_NAME = 'name';
     /**
      * @var string[]
      */
-    private $keys = [self::KEY_ALPHA2, self::KEY_ALPHA3, self::KEY_NUMERIC];
+    private $keys = [self::KEY_ALPHA2, self::KEY_ALPHA3, self::KEY_NUMERIC, self::KEY_NAME];
 
     /**
      * @param array[] $countries replace default dataset with given array
@@ -41,6 +45,16 @@ public function __construct(array $countries = [])
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function name($name)
+    {
+        Guards::guardAgainstInvalidName($name);
+
+        return $this->lookup(self::KEY_NAME, $name);
+    }
+
     /**
      * {@inheritdoc}
      */

src/ISO3166DataProvider.php

@@ -11,6 +11,20 @@
 
 interface ISO3166DataProvider
 {
+    /**
+     * Lookup ISO3166-1 data by name identifier.
+     *
+     * @api
+     *
+     * @param string $name
+     *
+     * @throws \League\ISO3166\Exception\InvalidArgumentException if input is not a string
+     * @throws \League\ISO3166\Exception\OutOfBoundsException if input does not exist in dataset
+     *
+     * @return array
+     */
+    public function name($name);
+
     /**
      * Lookup ISO3166-1 data by alpha2 identifier.
      *