<picture> <source srcset="https://github.com/PrinsFrank/standards/raw/main/docs/images/banner_dark.png" media="(prefers-color-scheme: dark)"> <img src="https://github.com/PrinsFrank/standards/raw/main/docs/images/banner_light.png" alt="Banner"> </picture>

Standards

A collection of standards as PHP Enums

Daily updated from their sources, whether it is ISO or IANA directly, or a maintaining party like the SIX Group or the US Library of Congress.

Setup

Note Make sure you are running PHP 8.1 or higher to use this package

To start right away, run the following command in your composer project;

composer require prinsfrank/standards

Or for development only;

composer require prinsfrank/standards --dev

Daily updated from their source

How this package works

This package implements a bunch of specs as PHP Enums, so you can typehint them in methods. Currently, all specs are implemented as backed enums. That means that besides a name, they have also an internal 'value', either as an integer or a string.

In the Country, Currency and language specifications, there is also a relation between different enums. For example, the Alpha2 country code 'NL' is related to the Alpha3 'NLD', the numeric value '528' and the name 'Netherlands (the)'. Internally, these specs rely on the fact that the keys for these values are identical, so it is possible to convert between these.

Entities and their relations

All specifications in this package are closely related, except for the Http status code and methods. Not all relations are bidirectional though. For example, a language tag is build up of a language and optionally a country, but only a country cannot be converted to a language tag.

Below you can find an overview of all the relationships between specifications.

erDiagram
    Country {
        class CountryAlpha2
        class CountryAlpha3
        class CountryNumeric
        class CountryName
    }
    GeographicRegion {
        class GeographicRegion
    }
    CountryGroup {
        class BRICS
        class EEA
        class EFTA
        class EU
        class EuroZone
        class NATO
        class Schengen
        class WorldTradeOrganization
    }
    CountryCallingCode {
        class CountryCallingCode
    }
    CountrySubdivision {
        class CountrySubdivision
    }
    Currency {
        class CurrencyAlpha3
        class CurrencyName
        class CurrencyNumeric
    }
    CurrencyMinorUnits {
        class CurrencyMinorLowerLastAlpha3
        class CurrencyMinorUpperXAlpha3
    }
    CurrencySymbol {
        class CurrencySymbol
    }
    NationalCallPrefix {
        class NationalCallPrefix
    }
    InternationalCallPrefix {
        class InternationalCallPrefix
    }
    Language {
        class LanguageName
        class LanguageAlpha2
        class LanguageAlpha3Common
        class LanguageAlpha3Bibliographic
        class LanguageAlpha3Terminology
        class LanguageAlpha3Extensive
    }
    Script {
        class ScriptAlias
        class ScriptCode
        class ScriptName
        class ScriptNumber
    }
    LanguageTag {
        class LanguageTag
        class LanguageTagVariant
        class PrivateUsePrimarySubtag
        class SingleCharacterSubtag
    }
    HttpMethod {
        class HtppMethod
    }
    HttpStatusCode {
        class HttpStatusCode
    }
    TLD {
        class CountryCodeTLD
        class GenericRestrictedTLD
        class GenericTLD
        class InfrastructureTLD
        class SponsoredTLD
        class TestTLD
    }

    Country ||--o{ CountrySubdivision: ""
    Country ||--o{ Country: ""
    GeographicRegion }|--o{ Country: ""
    GeographicRegion ||--o{ GeographicRegion: ""
    Language }o--o{ Country: ""
    Country }|--o{ CountryGroup: ""
    Country }|--o{ CountryCallingCode: ""
    Country }o--o{ Currency: ""
    Country }|--o{ NationalCallPrefix: ""
    Country }|--o{ InternationalCallPrefix: ""
    Currency }|--o| CurrencySymbol: ""
    Currency }|--o| CurrencyMinorUnits: ""
    LanguageTag ||--o{ LanguageTag: ""
    Language }|--o{ LanguageTag: ""
    Script |o--o{ LanguageTag: ""
    Country |o--o{ LanguageTag: ""
    TLD ||--o| Country: ""
    LanguageTag }o--o| GeographicRegion: ""

Upgrading

This package adheres to semver. This means that there are no breaking changes between minor releases (for example from 1.1 to 1.2), but that breaking changes are released as a major release (for example from 1.x to 2.x). To read about upgrading from one major release to the next, please refer to the UPGRADING.md file in the root of this project.

Some powerful use cases

Format a complete phone number string based on the users country;

Automatically select a supported language from an HTTP request;

Listing all country calling codes sorted by country name in a dropdown;

Country (ISO3166-1)

:mortar_board: Alpha2/3 country codes are always UPPERCASE to avoid confusion with language codes. It is recommended to use Alpha2/Alpha3 codes when exposing the specification in APIs

At a glance

All the Alpha2, Alpha3, Numeric and Name values have a corresponding enum in the other country enums. These can be converted using their corresponding methods (toAlpha2, toAlpha3 etc...).

Country group membership can be checked by calling the isMemberOf method, supplying the FQN of a class that implements the GroupInterface. Several country groups are available: BRICS, EEA, EFTA etc. Countries can also have subdivisions, which can be of several types: countries, provinces, etc.

use PrinsFrank\Standards\Country\CountryAlpha2;
use PrinsFrank\Standards\Country\CountryAlpha3;
use PrinsFrank\Standards\Country\CountryNumeric;
use PrinsFrank\Standards\Country\Groups\EU;
use PrinsFrank\Standards\Language\LanguageAlpha2;

CountryAlpha2::from('NL');                                      // CountryAlpha2::Netherlands
CountryNumeric::from('528');                                    // CountryNumeric::Netherlands
CountryNumeric::fromInt(528);                                   // CountryNumeric::Netherlands
Co