diff options
Diffstat (limited to 'library/intl/README.md')
| -rw-r--r-- | library/intl/README.md | 163 |
1 files changed, 0 insertions, 163 deletions
diff --git a/library/intl/README.md b/library/intl/README.md deleted file mode 100644 index 8de2de4d9..000000000 --- a/library/intl/README.md +++ /dev/null @@ -1,163 +0,0 @@ -intl -===== - -[](https://travis-ci.org/commerceguys/intl) - -A PHP 5.4+ internationalization library, powered by CLDR data. - -Features: -- NumberFormatter, inspired by [intl](http://php.net/manual/en/class.numberformatter.php). -- Currencies -- Countries -- Languages - -Coming soon: date formatting. - -Why not use the intl extension? -------------------------------- -The intl extension isn't present by default on PHP installs, requiring -it can hurt software adoption. -Behind the scenes the extension relies on libicu which includes the CLDR dataset, -but depending on the OS/distribution used, could be several major CLDR releases behind. - -Since the CLDR dataset is freely available in JSON form, it is possible to -reimplement the intl functionality in pure PHP code while ensuring that the -dataset is always fresh. - -Having access to the CLDR dataset also makes it possible to offer additional APIs, -such as listing all currencies. - -More backstory can be found in [this blog post](https://drupalcommerce.org/blog/15916/commerce-2x-stories-internationalization). - -Formatting numbers ------------------- -Formats numbers (decimals, percents, currency amounts) using locale-specific rules. - -This ensures that the decimal and grouping separators, the position of the currency -symbol, as well as the actual symbol used match what the user is expecting. - -The amounts passed for formatting should already be rounded, because the -formatter doesn't do any rounding of its own. - -```php -use CommerceGuys\Intl\Currency\CurrencyRepository; -use CommerceGuys\Intl\NumberFormat\NumberFormatRepository; -use CommerceGuys\Intl\Formatter\NumberFormatter; - -$currencyRepository = new CurrencyRepository; -$numberFormatRepository = new NumberFormatRepository; - -$currency = $currencyRepository->get('USD'); -$numberFormat = $numberFormatRepository->get('en'); - -$decimalFormatter = new NumberFormatter($numberFormat); -echo $decimalFormatter->format('1234.99'); // 123,456.99 - -$percentFormatter = new NumberFormatter($numberFormat, NumberFormatter::PERCENT); -echo $percentFormatter->format('0.75'); // 75% - -$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); -echo $currencyFormatter->formatCurrency('2.99', $currency); // $2.99 - -// The accounting pattern shows negative numbers differently and is used -// primarily for amounts shown on invoices. -$invoiceCurrencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY_ACCOUNTING); -echo $invoiceCurrencyFormatter->formatCurrency('-2.99', $currency); // (2.99$) - -// Arabic, Arabic extended, Bengali, Devanagari digits are supported as expected. -$currency = $currencyRepository->get('USD', 'ar'); -$numberFormat = $numberFormatRepository->get('ar'); -$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); -echo $currencyFormatter->formatCurrency('1230.99', $currency); // US$ ١٬٢٣٠٫٩٩ - -// Parse formatted values into numeric values. -echo $currencyFormatter->parseCurrency('US$ ١٬٢٣٠٫٩٩', $currency); // 1230.99 -``` - -Currencies ----------- -```php -use CommerceGuys\Intl\Currency\CurrencyRepository; - -// Reads the currency definitions from resources/currency. -$currencyRepository = new CurrencyRepository; - -// Get the USD currency using the default locale (en). -$currency = $currencyRepository->get('USD'); -echo $currency->getCurrencyCode(); // USD -echo $currency->getNumericCode(); // 840 -echo $currency->getFractionDigits(); // 2 -echo $currency->getName(); // US Dollar -echo $currency->getSymbol(); // $ -echo $currency->getLocale(); // en - -// Get the USD currency using the fr-FR locale. -$currency = $currencyRepository->get('USD', 'fr-FR'); -echo $currency->getName(); // dollar des États-Unis -echo $currency->getSymbol(); // $US -echo $currency->getLocale(); // fr-FR - -$allCurrencies = $currencyRepository->getAll(); -``` - -Countries ---------- -```php -use CommerceGuys\Intl\Country\CountryRepository; - -// Reads the country definitions from resources/country. -$countryRepository = new CountryRepository; - -// Get the US country using the default locale (en). -$country = $countryRepository->get('US'); -echo $country->getCountryCode(); // US -echo $country->getTelephoneCode(); // 1 -echo $country->getName(); // United States - -// Get the US country using the fr-FR locale. -$country = $countryRepository->get('US', 'fr-FR'); -echo $country->getName(); // États-Unis - -$allCountries = $countryRepository->getAll(); -``` - -Languages ---------- -```php -use CommerceGuys\Intl\Language\LanguageRepository; - -// Reads the language definitions from resources/language. -$languageRepository = new LanguageRepository; - -// Get the german language using the default locale (en). -$language = $languageRepository->get('de'); -echo $language->getLanguageCode(); // de -echo $language->getName(); // German - -// Get the german language using the fr-FR locale. -$language = $languageRepository->get('de', 'fr-FR'); -echo $language->getName(); // allemand - -$allLanguages = $languageRepository->getAll(); -``` - -Implementing the library ------------------------- -While the library can be used as-is, most applications will want to store the -relevant definitions (currencies, countries, etc) in the database. -This allows for better performance while giving users the ability to modify and -expand the data. - -Taking currencies as an example, a merchant frequently wants to be able to: - -- Define custom currencies. -- Enable/disable existing currencies -- Modify an existing currency (changing the default number of fraction digits, for example). - -This would be accomplished by using the CurrencyRepository to get all default currencies and -insert them into the database. The doctrine entity (or any similar data object) would then implement -the CurrencyInterface so that the NumberFormatter can continue to work. - -Related projects ----------------- -[commerceguys/pricing](http://github.com/commerceguys/pricing) provides a Price object. |