Hello World

.gitattributes

@@ -0,0 +1,11 @@
+* text=auto
+
+.github/ export-ignore
+tests/ export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/infection.json5.dist export-ignore
+/phpcs.xml.dist export-ignore
+/phpunit.xml.dist export-ignore
+/psalm.xml export-ignore
+/README.md export-ignore

.github/workflows/mutation-tests.yml

@@ -0,0 +1,34 @@
+name: Mutation tests
+
+on:
+    push:
+        paths:
+            - '**workflows/mutation-tests.yml'
+            - '**.php'
+            - '**composer.json'
+            - '**infection.json5.dist'
+            - '**phpunit.xml.dist'
+    pull_request:
+        paths:
+            - '**workflows/mutation-tests.yml'
+            - '**.php'
+            - '**composer.json'
+            - '**infection.json5.dist'
+            - '**phpunit.xml.dist'
+    workflow_dispatch:
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    mutation-tests:
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: actions/checkout@v4
+            -   uses: shivammathur/setup-php@v2
+                with:
+                    php-version: '8.3'
+                    tools: infection
+            -   uses: ramsey/composer-install@v3
+            -   run: infection --min-covered-msi=95 --no-progress --log-verbosity=none --threads=max

.github/workflows/static-analysis.yml

@@ -0,0 +1,58 @@
+name: Static analysis
+
+on:
+    push:
+        paths:
+            - '**workflows/static-analysis.yml'
+            - '**.php'
+            - '**composer.json'
+            - '**phpcs.xml.dist'
+            - '**psalm.xml'
+    pull_request:
+        paths:
+            - '**workflows/static-analysis.yml'
+            - '**.php'
+            - '**composer.json'
+            - '**phpcs.xml.dist'
+            - '**psalm.xml'
+    workflow_dispatch:
+        inputs:
+            jobs:
+                required: true
+                type: choice
+                default: 'Run all'
+                description: 'Choose jobs to run'
+                options:
+                    - 'Run all'
+                    - 'Run PHPCS only'
+                    - 'Run Psalm only'
+                    - 'Run lint only'
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    lint-php:
+        uses: inpsyde/reusable-workflows/.github/workflows/lint-php.yml@main
+        if: ${{ (github.event_name != 'workflow_dispatch') || ((github.event.inputs.jobs == 'Run all') || (github.event.inputs.jobs == 'Run lint only')) }}
+        strategy:
+            fail-fast: false
+            matrix:
+                php-ver: [ '8.3', '8.4' ]
+        with:
+            PHP_VERSION: ${{ matrix.php-ver }}
+
+    coding-standards-analysis-php:
+        if: ${{ (github.event_name != 'workflow_dispatch') || ((github.event.inputs.jobs == 'Run all') && (github.event.inputs.jobs == 'Run PHPCS only')) }}
+        uses: inpsyde/reusable-workflows/.github/workflows/coding-standards-php.yml@main
+
+    static-code-analysis-php:
+        if: ${{ (github.event_name != 'workflow_dispatch') || ((github.event.inputs.jobs == 'Run all') && (github.event.inputs.jobs == 'Run Psalm only')) }}
+        uses: inpsyde/reusable-workflows/.github/workflows/static-analysis-php.yml@main
+        strategy:
+            fail-fast: false
+            matrix:
+                php-ver: [ '8.3' ]
+        with:
+            PHP_VERSION: ${{ matrix.php-ver }}

.github/workflows/unit-tests.yml

@@ -0,0 +1,57 @@
+name: Unit tests
+
+on:
+    push:
+        paths:
+            - '**workflows/unit-tests.yml'
+            - '**.php'
+            - '**composer.json'
+            - '**phpunit.xml.dist'
+    pull_request:
+        paths:
+            - '**workflows/unit-tests.yml'
+            - '**.php'
+            - '**composer.json'
+            - '**phpunit.xml.dist'
+    workflow_dispatch:
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    unit-tests:
+        runs-on: ubuntu-latest
+        strategy:
+            fail-fast: false
+            matrix:
+                php-ver: [ '8.3', '8.4' ]
+        steps:
+            -   name: Set "USE_COVERAGE" env var based on matrix
+                run: echo "USE_COVERAGE=${{ matrix.php-ver == '8.3' }}" >> $GITHUB_ENV
+
+            -   name: Checkout
+                uses: actions/checkout@v4
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: ${{ matrix.php-ver }}
+                    ini-values: zend.assertions=1, error_reporting=E_ALL, display_errors=On
+                    coverage: ${{ ((env.USE_COVERAGE == 'yes') && 'xdebug') || 'none' }}
+
+            -   name: Adjust Composer dependencies
+                run:  composer remove --dev --no-update inpsyde/php-coding-standards phpcompatibility/php-compatibility vimeo/psalm
+
+            -   name: Install dependencies
+                uses: ramsey/composer-install@v3
+
+            -   name: Run unit tests
+                run: ./vendor/bin/phpunit ${{ ((env.USE_COVERAGE == 'yes') && '--coverage-clover coverage.xml') || '--no-coverage' }}
+
+            -   name: Update coverage
+                if: ${{ env.USE_COVERAGE == 'yes' }}
+                uses: codecov/codecov-action@v4
+                with:
+                    token: ${{ secrets.CODECOV_TOKEN }}
+                    file: ./coverage.xml

.gitignore

@@ -0,0 +1,6 @@
+.idea/
+vendor/
+.phpunit.cache/
+/composer.lock
+/phpunit.xml
+/.phpunit.result.cache

LICENSE

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Giuseppe Mazzapica and contributors.
+
+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.

README.md

@@ -0,0 +1,150 @@
+# BCP 47
+
+**PHP helpers to validate and normalize [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag).**~~
+~~
+---
+
+[![Static Analysis](https://github.com/Toobo/bcp47/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/Toobo/bcp47/actions/workflows/static-analysis.yml)
+[![Unit Tests](https://github.com/Toobo/bcp47/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/Toobo/bcp47/actions/workflows/unit-tests.yml)
+[![Mutation Tests](https://img.shields.io/badge/Mutation_Tests-Min_Covered_MSI_95%25-green?style=flat&logo=php&logoColor=%23F0F0F0)](https://github.com/Toobo/bcp47/actions/workflows/mutation-tests.yml)
+
+---
+
+
+## Utility functions
+
+```php
+$isValid = Toobo\Bcp47::isValidTag('i-klingon');  // true
+$isValid = Toobo\Bcp47::isValidTag('xy');         // false
+
+$filtered = Toobo\Bcp47::filterTag('EN-us');      // "en-US"
+$filtered = Toobo\Bcp47::filterTag('fr-latn-fx'); // "fr-FR"
+
+$isRTL = Toobo\Bcp47::isRtl('he');                // true
+$isRTL = Toobo\Bcp47::isRtl('en-us');             // false
+
+var_export(Toobo\Bcp47::splitTag('En-ca-Newfound'));
+array (
+  'language' => 'en',
+  'extLang' => '',
+  'script' => '',
+  'region' => 'CA',
+  'variant' => 'newfound',
+  'extension' => '',
+  'privateUse' => '',
+)
+```
+
+
+
+## The `Bcp47Tag` class
+
+The `Toobo\Bcp47Tag` offers an API similar to the utility functions, but it ensure it encapsulate
+a valid tag, in fact it throws when instantiated with an invalid tag.
+
+The class is `Stringable` and `JsonSerializable`, and it also implements the `Bcp47Code` interface
+defined by the [**`wikimedia/bcp-47-code`**](https://packagist.org/packages/wikimedia/bcp-47-code)
+package.
+
+```php
+$tag = Toobo\Bcp47Tag::new('En-ca-Newfound');
+
+assert($tag->isSameCodeAs(Toobo\Bcp47Tag::new('en-CA-newfound')) === true);
+
+assert($tag->language() === 'en');
+assert($tag->extLang() === null);
+assert($tag->script() === null);
+assert($tag->region() === 'CA');
+assert($tag->variant() === 'newfound');
+assert($tag->extension() === null);
+assert($tag->privateUse() === null);
+assert($tag->isRtl() === false);
+
+assert((string) $tag === 'en-CA-newfound');
+
+assert(json_encode($tag) === '{"language":"en","region":"CA","variant":"newfound"}');
+```
+
+
+
+## Validation
+
+The `Bcp47Tag` class, as well as the `Bcp47::isValidTag()`, `Bcp47::filterTag()`, and 
+`Bcp47::splitTag()` functions, all do validation.
+
+The class throw on instantiation for invalid tags, while the functions returns, respectively,
+`false`, `null`, and an array with all empty items.
+
+The validation is not just about the _format_ but also the actual values. For example, `xy-IT`
+looks like a valid tag, but the language "xy" does not exist, so the the tag is not valid.
+
+The validation apply to all subtags (but "extension" and "privateUse"), and also _across_ subtags.
+For example, the tag `ca-valencia` is valid (_Valencia variant of the Catalan language_),
+but `en-valencia` is not, despite the language "en" and the variant "valencia" being valid per-se,
+because there is no "valencia" variant for the English language.
+
+
+
+## Normalization
+
+The `Bcp47Tag` class, as well as both `Bcp47::filterTag()` and `Bcp47::splitTag()` functions
+"normalize" the given tag.
+
+Normalization includes:
+- Replace deprecated values with the new accepted value, when available. For example, the region
+  code for the "Democratic Republic of the Congo" (formerly "Zaire") "ZR" is replaced with "CD".
+- Case normalization (all lowercase, but uppercase region and title-case script.
+- Replacement of numeric region codes with 2-chars alpha code, when available.
+- Replacement of 3-chars language code (ISO 639-3) with 2-chars code (ISO 636-1), when available.
+
+
+
+## FAQ
+
+- Why is `Bc47` an **enum**?
+
+This package's utility functions are stateless and pure PHP _functions_.
+
+However, plain PHP functions can't be autoloaded. By using a case-less PHP enum, we get autoloading,
+but unlike when using a class, we prevent anyone to extend or instantiate the class without 
+intervening on the runtime code.
+
+A case-less PHP enum is a _de facto_ autoload-enabling namespace for functions.
+
+
+
+## Installation
+
+Best served via Composer, the package name is `toobo/bcp47`.
+
+```bash
+composer require "toobo/bcp47:^1"
+```
+
+
+
+## Requirements
+
+BCP 47 requires PHP 8.3+, and requires via Composer:
+
+- "wikimedia/bcp-47-code" (GPL v2)
+
+When installed for development, it also requires via Composer:
+
+- "phpunit/phpunit" (BSD-3-Clause)
+- "inpsyde/php-coding-standards" (MIT)
+- "vimeo/psalm" (MIT)
+
+
+
+## Security Issues
+
+If you have identified a security issue, please email giuseppe.mazzapica [at] gmail.com and do not file an issue as they are public.
+
+
+
+## License
+
+Copyright (c), Giuseppe Mazzapica, and contributors.
+
+This software is released under the ["MIT"](LICENSE) license.