refactor: Improves strict typing and tests. Also updates documentation for Alpha codes and Country usage examples. (#10)

Author: gustavofreze

.gitattributes

@@ -0,0 +1,14 @@
+/tests export-ignore
+/vendor export-ignore
+
+/README.md export-ignore
+/LICENSE export-ignore
+/Makefile export-ignore
+/phpmd.xml export-ignore
+/phpunit.xml export-ignore
+/phpstan.neon.dist export-ignore
+/infection.json.dist export-ignore
+
+/.github export-ignore
+/.gitignore export-ignore
+/.gitattributes export-ignore

.github/workflows/ci.yml

@@ -16,6 +16,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
+      - name: Use PHP 8.2
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
       - name: Install dependencies
         run: composer update --no-progress --optimize-autoloader
 
@@ -33,6 +38,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
+      - name: Use PHP 8.2
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
       - name: Install dependencies
         run: composer update --no-progress --optimize-autoloader
 

Makefile

@@ -1,19 +1,25 @@
 DOCKER_RUN = docker run --rm -it --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.2
 
-.PHONY: configure test test-no-coverage review show-reports clean
+.PHONY: configure test test-file test-no-coverage review fix-style show-reports clean
 
 configure:
 	@${DOCKER_RUN} composer update --optimize-autoloader
 
-test: review
+test:
 	@${DOCKER_RUN} composer tests
 
-test-no-coverage: review
+test-file:
+	@${DOCKER_RUN} composer tests-file-no-coverage ${FILE}
+
+test-no-coverage:
 	@${DOCKER_RUN} composer tests-no-coverage
 
 review:
 	@${DOCKER_RUN} composer review
 
+fix-style:
+	@${DOCKER_RUN} composer fix-style
+
 show-reports:
 	@sensible-browser report/coverage/coverage-html/index.html report/coverage/mutation-report.html
 

README.md

@@ -12,7 +12,7 @@
 
 ## Overview
 
-Value Object representing a country using ISO-3166 specifications.
+Value Object representing a country using [ISO-3166 specifications](https://www.iso.org/iso-3166-country-codes.html).
 
 <div id='installation'></div>
 
@@ -26,12 +26,13 @@ composer require tiny-blocks/country
 
 ## How to use
 
-The library exposes country codes according to ISO-3166 specifications. Also, it is possible to create a
+The library exposes country codes according
+to [ISO-3166 specifications](https://www.iso.org/iso-3166-country-codes.html). Also, it is possible to create a
 representation of a country that groups the codes and its name.
 
 ### Alpha2Code
 
-**Alpha-2 code**: a two-letter code that represents a country name, recommended as the general purpose code.
+A two-letter code that represents a country name, recommended as the general purpose code.
 
 ```php
 $alpha2Code = Alpha2Code::UNITED_STATES_OF_AMERICA;
@@ -43,7 +44,7 @@ $alpha2Code->toAlpha3()->value; # USA
 
 ### Alpha3Code
 
-**Alpha-3 code**: a three-letter code that represents a country name, which is usually more closely related to the
+A three-letter code that represents a country name, which is usually more closely related to the
 country name.
 
 ```php
@@ -56,11 +57,15 @@ $alpha3Code->toAlpha2()->value; # US
 
 ### Country
 
-A country might change a significant part of its name, so there is no specific ISO for this case.
+A `Country` instance can be created using either an `Alpha-2` or `Alpha-3` code, along with an optional country name.
+There are two main methods to create a `Country` object: `from` (which accepts objects) and `fromString` (which accepts
+strings).
 
-You can create an instance of `Country`, using the `from` method, informing an alpha code (`Alpha2Code`or `Alpha3Code`),
-where they can be of type `AlphaCode` or just `strings`. Optionally, you can enter the name of the country. If the
-country name is not given in the `from` method, then the default is to assume an English version of the country name.
+#### Creating from objects
+
+You can create a `Country` instance using the `from` method by providing an `Alpha2Code` or `Alpha3Code` object.
+Optionally, you can pass the name of the country. If no name is provided, the default is the English version of the
+country name.
 
 ```php
 $country = Country::from(alphaCode: Alpha2Code::UNITED_STATES_OF_AMERICA);
@@ -73,14 +78,14 @@ $country->alpha3->value; # USA
 or
 
 ```php
-$country = Country::from(alphaCode: 'US');
+$country = Country::from(alphaCode: Alpha3Code::UNITED_STATES_OF_AMERICA);
 
 $country->name;          # United States of America
 $country->alpha2->value; # US
 $country->alpha3->value; # USA
 ```
 
-Creating an instance passing the country name.
+If you want to specify a custom name:
 
 ```php
 $country = Country::from(alphaCode: Alpha3Code::UNITED_STATES_OF_AMERICA, name: 'United States');
@@ -90,6 +95,29 @@ $country->alpha2->value; # US
 $country->alpha3->value; # USA
 ```
 
+#### Creating from string
+
+Alternatively, you can create a `Country` instance using the `fromString` method, which accepts an `Alpha-2` or
+`Alpha-3` code as a string. This method is useful when the alpha code is provided as a string.
+
+```php
+$country = Country::fromString(alphaCode: 'US');
+
+$country->name;          # United States of America
+$country->alpha2->value; # US
+$country->alpha3->value; # USA
+```
+
+You can also pass a custom country name when using the `fromString` method:
+
+```php
+$country = Country::fromString(alphaCode: 'USA', name: 'United States');
+
+$country->name;          # United States
+$country->alpha2->value; # US
+$country->alpha3->value; # USA
+```
+
 <div id='license'></div>
 
 ## License

composer.json

@@ -9,8 +9,6 @@
     "keywords": [
         "vo",
         "psr",
-        "psr-4",
-        "psr-12",
         "country",
         "tiny-blocks",
         "value-object"
@@ -21,6 +19,10 @@
             "homepage": "https://github.com/gustavofreze"
         }
     ],
+    "support": {
+        "issues": "https://github.com/tiny-blocks/country/issues",
+        "source": "https://github.com/tiny-blocks/country"
+    },
     "config": {
         "sort-packages": true,
         "allow-plugins": {
@@ -38,25 +40,28 @@
         }
     },
     "require": {
-        "php": "^8.1||^8.2",
-        "tiny-blocks/value-object": "^2.0"
+        "php": "^8.2",
+        "tiny-blocks/value-object": "^2"
     },
     "require-dev": {
-        "infection/infection": "^0.26",
-        "phpmd/phpmd": "^2.13",
-        "phpunit/phpunit": "^9.6",
-        "squizlabs/php_codesniffer": "^3.7"
+        "phpmd/phpmd": "^2.15",
+        "phpstan/phpstan": "^1",
+        "phpunit/phpunit": "^11",
+        "infection/infection": "^0.29",
+        "squizlabs/php_codesniffer": "^3.10"
     },
     "scripts": {
         "phpcs": "phpcs --standard=PSR12 --extensions=php ./src",
         "phpmd": "phpmd ./src text phpmd.xml --suffixes php --exclude /src/Alpha2Code.php,/src/Alpha3Code.php --ignore-violations-on-exit",
+        "phpstan": "phpstan analyse -c phpstan.neon.dist --quiet --no-progress",
         "test": "phpunit --log-junit=report/coverage/junit.xml --coverage-xml=report/coverage/coverage-xml --coverage-html=report/coverage/coverage-html tests",
         "test-mutation": "infection --only-covered --logger-html=report/coverage/mutation-report.html --coverage=report/coverage --min-msi=100 --min-covered-msi=100 --threads=4",
         "test-no-coverage": "phpunit --no-coverage",
         "test-mutation-no-coverage": "infection --only-covered --min-msi=100 --threads=4",
         "review": [
             "@phpcs",
-            "@phpmd"
+            "@phpmd",
+            "@phpstan"
         ],
         "tests": [
             "@test",
@@ -65,6 +70,9 @@
         "tests-no-coverage": [
             "@test-no-coverage",
             "@test-mutation-no-coverage"
+        ],
+        "tests-file-no-coverage": [
+            "@test-no-coverage"
         ]
     }
 }

infection.json.dist

@@ -1,28 +1,21 @@
 {
     "timeout": 10,
     "testFramework": "phpunit",
-    "tmpDir": "report/",
+    "tmpDir": "report/infection/",
     "source": {
         "directories": [
             "src"
         ]
     },
     "logs": {
-        "text": "report/logs/infection-text.log",
-        "summary": "report/logs/infection-summary.log"
+        "text": "report/infection/logs/infection-text.log",
+        "summary": "report/infection/logs/infection-summary.log"
     },
     "mutators": {
-        "@default": true,
-        "MBString": false,
-        "Ternary": false,
-        "Identical": false,
-        "DecrementInteger": false,
-        "IncrementInteger": false,
-        "PublicVisibility": false,
-        "ProtectedVisibility": false
+        "@default": true
     },
     "phpUnit": {
         "configDir": "",
         "customPath": "./vendor/bin/phpunit"
     }
-}
+}

phpstan.neon.dist

@@ -0,0 +1,8 @@
+parameters:
+  paths:
+    - src
+  level: 9
+  tmpDir: report/phpstan
+  ignoreErrors:
+    - '#value type specified in iterable type array#'
+  reportUnmatchedIgnoredErrors: false

phpunit.xml

@@ -1,25 +1,35 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         bootstrap="vendor/autoload.php"
-         cacheResultFile="report/.phpunit.result.cache"
-         backupGlobals="false"
-         backupStaticAttributes="false"
+         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false"
-         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+         bootstrap="vendor/autoload.php"
+         failOnRisky="true"
+         failOnWarning="true"
+         cacheDirectory=".phpunit.cache"
+         beStrictAboutOutputDuringTests="true">
+
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+
     <testsuites>
         <testsuite name="default">
-            <directory suffix="Test.php">tests</directory>
+            <directory>tests</directory>
         </testsuite>
     </testsuites>
 
     <coverage>
-        <include>
-            <directory suffix=".php">src</directory>
-        </include>
+        <report>
+            <text outputFile="report/coverage.txt"/>
+            <html outputDirectory="report/html/"/>
+            <clover outputFile="report/coverage-clover.xml"/>
+        </report>
     </coverage>
+
+    <logging>
+        <junit outputFile="report/execution-result.xml"/>
+    </logging>
+
 </phpunit>

src/Alpha2Code.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace TinyBlocks\Country;
 
 use TinyBlocks\Country\Internal\AlphaCode;

src/Alpha3Code.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace TinyBlocks\Country;
 
 use TinyBlocks\Country\Internal\AlphaCode;