Merge pull request #2 from tiny-blocks/release/1.0.0

Release/1.0.0

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: gustavofreze

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  auto-review:
+    name: Auto review
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: composer update --no-progress --optimize-autoloader
+
+      - name: Run phpcs
+        run: composer phpcs
+
+      - name: Run phpmd
+        run: composer phpmd
+
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: composer update --no-progress --optimize-autoloader
+
+      - name: Run unit tests
+        env:
+          XDEBUG_MODE: coverage
+        run: composer test
+
+      - name: Run mutation tests
+        run: composer test-mutation

.gitignore

@@ -0,0 +1,5 @@
+.idea
+vendor
+report
+composer.lock
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Tiny Blocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,22 @@
+DOCKER_RUN = docker run --rm -it --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.1.7
+
+.PHONY: configure test test-no-coverage review show-reports clean
+
+configure:
+	@${DOCKER_RUN} composer update --optimize-autoloader
+
+test: review
+	@${DOCKER_RUN} composer tests
+
+test-no-coverage: review
+	@${DOCKER_RUN} composer tests-no-coverage
+
+review:
+	@${DOCKER_RUN} composer review
+
+show-reports:
+	@sensible-browser report/coverage/coverage-html/index.html report/coverage/mutation-report.html
+
+clean:
+	@sudo chown -R ${USER}:${USER} ${PWD}
+	@rm -rf report vendor

README.md

@@ -1,2 +1,102 @@
-# country
+# Country
+
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+* [Overview](#overview)
+* [Installation](#installation)
+* [How to use](#how-to-use)
+* [License](#license)
+* [Contributing](#contributing)
+
+<div id='overview'></div> 
+
+## Overview
+
 Value Object representing a country using ISO-3166 specifications.
+
+<div id='installation'></div>
+
+## Installation
+
+```bash
+composer require tiny-blocks/country
+```
+
+<div id='how-to-use'></div>
+
+## How to use
+
+The library exposes country codes according to ISO-3166 specifications. 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.
+
+```php
+$alpha2Code = Alpha2Code::UNITED_STATES_OF_AMERICA;
+
+echo $alpha2Code->name;              # UNITED_STATES_OF_AMERICA
+echo $alpha2Code->value;             # US
+echo $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
+country name.
+
+```php
+$alpha3Code = Alpha3Code::UNITED_STATES_OF_AMERICA;
+
+echo $alpha3Code->name;              # UNITED_STATES_OF_AMERICA
+echo $alpha3Code->value;             # USA
+echo $alpha3Code->toAlpha2()->value; # US
+```
+
+### Country
+
+A country might change a significant part of its name, so there is no specific ISO for this case.
+
+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.
+
+```php
+$country = Country::from(alphaCode: Alpha2Code::UNITED_STATES_OF_AMERICA);
+
+echo $country->name;          # United States of America
+echo $country->alpha2->value; # US
+echo $country->alpha3->value; # USA
+```
+
+or
+
+```php
+$country = Country::from(alphaCode: 'US');
+
+echo $country->name;          # United States of America
+echo $country->alpha2->value; # US
+echo $country->alpha3->value; # USA
+```
+
+Creating an instance passing the country name.
+
+```php
+$country = Country::from(alphaCode: Alpha3Code::UNITED_STATES_OF_AMERICA, name: 'United States');
+
+echo $country->name;          # United States
+echo $country->alpha2->value; # US
+echo $country->alpha3->value; # USA
+```
+
+## License
+
+Math is licensed under [MIT](/LICENSE).
+
+<div id='contributing'></div>
+
+## Contributing
+
+Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to
+contribute to the project.

composer.json

@@ -0,0 +1,70 @@
+{
+    "name": "tiny-blocks/country",
+    "type": "library",
+    "license": "MIT",
+    "homepage": "https://github.com/tiny-blocks/country",
+    "description": "Value Object representing a country using ISO-3166 specifications.",
+    "prefer-stable": true,
+    "minimum-stability": "stable",
+    "keywords": [
+        "vo",
+        "psr",
+        "psr-4",
+        "psr-12",
+        "country",
+        "tiny-blocks",
+        "value-object"
+    ],
+    "authors": [
+        {
+            "name": "Gustavo Freze de Araujo Santos",
+            "homepage": "https://github.com/gustavofreze"
+        }
+    ],
+    "config": {
+        "sort-packages": true,
+        "allow-plugins": {
+            "infection/extension-installer": true
+        }
+    },
+    "autoload": {
+        "psr-4": {
+            "TinyBlocks\\Country\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "TinyBlocks\\Country\\": "tests/"
+        }
+    },
+    "require": {
+        "php": "^8.1",
+        "tiny-blocks/value-object": "^1.0"
+    },
+    "require-dev": {
+        "infection/infection": "^0.26",
+        "phpmd/phpmd": "^2.12",
+        "phpunit/phpunit": "^9.5",
+        "squizlabs/php_codesniffer": "^3.7"
+    },
+    "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",
+        "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"
+        ],
+        "tests": [
+            "@test",
+            "@test-mutation"
+        ],
+        "tests-no-coverage": [
+            "@test-no-coverage",
+            "@test-mutation-no-coverage"
+        ]
+    }
+}

infection.json.dist

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

phpmd.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+<ruleset name="PHPMD Custom rules"
+         xmlns="http://pmd.sf.net/ruleset/1.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
+         xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd">
+    <description>PHPMD Custom rules</description>
+
+    <rule ref="rulesets/cleancode.xml/ElseExpression"/>
+    <rule ref="rulesets/cleancode.xml/BooleanArgumentFlag"/>
+
+    <rule ref="rulesets/codesize.xml/TooManyFields"/>
+    <rule ref="rulesets/codesize.xml/TooManyMethods"/>
+    <rule ref="rulesets/codesize.xml/NPathComplexity"/>
+    <rule ref="rulesets/codesize.xml/CyclomaticComplexity"/>
+    <rule ref="rulesets/codesize.xml/ExcessivePublicCount"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveClassLength"/>
+    <rule ref="rulesets/codesize.xml/TooManyPublicMethods"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveMethodLength"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveParameterList"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveClassComplexity"/>
+
+    <rule ref="rulesets/controversial.xml/Superglobals"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseClassName"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseMethodName"/>
+    <rule ref="rulesets/controversial.xml/CamelCasePropertyName"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseVariableName"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseParameterName"/>
+
+    <rule ref="rulesets/design.xml/GotoStatement"/>
+    <rule ref="rulesets/design.xml/ExitExpression"/>
+    <rule ref="rulesets/design.xml/EvalExpression"/>
+    <rule ref="rulesets/design.xml/NumberOfChildren"/>
+    <rule ref="rulesets/design.xml/DepthOfInheritance"/>
+    <rule ref="rulesets/design.xml/CouplingBetweenObjects"/>
+    <rule ref="rulesets/design.xml/DevelopmentCodeFragment"/>
+
+    <rule ref="rulesets/naming.xml/LongVariable"/>
+    <rule ref="rulesets/naming.xml/ShortVariable">
+        <properties>
+            <property name="minimum" value="2"/>
+        </properties>
+    </rule>
+    <rule ref="rulesets/naming.xml/ShortMethodName">
+        <properties>
+            <property name="minimum" value="2"/>
+        </properties>
+    </rule>
+    <rule ref="rulesets/naming.xml/BooleanGetMethodName"/>
+    <rule ref="rulesets/naming.xml/ConstantNamingConventions"/>
+    <rule ref="rulesets/naming.xml/ConstructorWithNameAsEnclosingClass"/>
+
+    <rule ref="rulesets/unusedcode.xml/UnusedPrivateField"/>
+    <rule ref="rulesets/unusedcode.xml/UnusedLocalVariable"/>
+    <rule ref="rulesets/unusedcode.xml/UnusedPrivateMethod"/>
+    <rule ref="rulesets/unusedcode.xml/UnusedFormalParameter"/>
+</ruleset>

phpunit.xml

@@ -0,0 +1,25 @@
+<?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"
+         colors="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+    <testsuites>
+        <testsuite name="default">
+            <directory suffix="Test.php">tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage>
+        <include>
+            <directory suffix=".php">src</directory>
+        </include>
+    </coverage>
+</phpunit>