Punic¶
Punic is an easy way to access the Unicode CLDR localization data.
It’s a library for PHP 5.3+ that does not have any dependency on other libraries.
Installation¶
Manual installation¶
In case you can’t use composer (or even if you don’t know it), you can manually add Punic to your project and use it. Simply download the latest version from the Punic releases page.
Extract the zip archive somewhere accessible by your project and make sure you include the punic.php
file found in the zip archive.
Installation using composer¶
As Punic is written using PSR-4, it’s highly recommended to use composer to use it. Begin by editing your composer project by running.
composer require "punic/punic:^3"
That’s all it takes, you’re ready to go! Have a look at the example on the right to see how a basic call to punic can look like.
Classes¶
Punic offers a few classes that you can use in your projects.
Punic\Calendar
class¶
The calendar class contains a number of methods to localize date object related outputs.
formatDate
to format a date, getEraName
to return the name of an era, getMonthName
to do the same for months.
You can also find some helper methods like toDateTime
to convert a date/time representation to a DateTime
object.
use Punic\Calendar;
include 'vendor/autoload.php';
$dt = Calendar::toDateTime('2010-03-07');
echo Calendar::getEraName(1);
// Output: AD
echo Calendar::getMonthName($dt, 'abbreviated');
// Output: Mar
echo Calendar::getMonthName($dt, 'wide', 'it');
// Output: marzo
echo Calendar::getWeekdayName(1);
// Output: Monday
echo Calendar::getQuarterName(1);
// Output: 1st quarter
echo Calendar::format($dt, 'd MMMM y', 'de');
// Output: 7 März 2010
echo Calendar::formatDate($dt, 'full', 'it');
// Output: domenica 7 marzo 2010
echo Calendar::formatDate($dt, '~yMd', 'da');
// Output: 7/3/2010
$dt2 = Calendar::toDateTime('2010-03-10');
echo Calendar::formatInterval($dt, $dt2, 'yMMMd');
// Output: Mar 7 – 10, 2010
Punic\Currency
class¶
Need to know the currency used in a country? Do you want to have a list of all the currencies and their localized name? Use this class!
use Punic\Currency;
echo Currency::getCurrencyForTerritory('US');
// Output: USD (the currency code for US Dollars)
echo Currency::getName('USD');
// Output: the name of USD in the current default Punic locale
var_export(Currency::getCurrencyHistoryForTerritory('IT'));
// Output: the history of currencies used in Italy (from Italian Lira to Euro)
Punic\Data
class¶
If you work with a larger application, you probably don’t want to specify the locale for each string you want to localize.
You can use the Data
class to set a globally active locale and then skip the locale parameter when calling a method to localize a string.
use Punic\Data;
use Punic\Language;
Data::setDefaultLocale('de_DE');
echo Language::getName('de_CH');
// Output: Schweizer Hochdeutsch (Schweiz)
// without specifying a second parameter for Language::getName()
Data::setFallbackLocale('it_IT');
echo Language::getName('de_CH', 'et_INVALID');
// Output: alto tedesco svizzero (Svizzera)
// because the value in the second parameter of Language::getName() isn't a valid locale
Punic\Language
class¶
The language class helps you to convert a locale code into a language name. Want to know what it_IT is called in American English? Use this class to show all the languages in the right way.
use Punic\Language;
echo Language::getName('it_IT', 'en_US');
// Output: Italian (Italy)
echo Language::getName('de_CH', 'de_DE');
// Output: Schweizer Hochdeutsch (Schweiz)
Punic\Misc
class¶
Use the misc class to join a list of numbers correctly into a single string.
use Punic\Misc;
echo Misc::joinUnits(array('1 yd', '1 ft', '3 in'), '', 'en');
// Output: 1 yd, 1 ft, 3 in
echo Misc::joinUnits(array('1 yd', '1 ft', '3 in'), '', 'de');
// Output: 1 yd, 1 ft und 3 in
echo Misc::joinAnd(array('One', 'two', 'three'), '', 'en');
// Output: One, two, and three
echo Misc::joinAnd(array('Eins', 'Zwei', 'Drei'), '', 'de');
// Output: Eins, Zwei und Drei
echo Misc::joinOr(array('One', 'two', 'three'), '', 'en');
// Output: One, two, or three
echo Misc::joinOr(array('Eins', 'Zwei', 'Drei'), '', 'de');
// Output: Eins, Zwei oder Drei
Punic\Number
class¶
The number class offers methods to convert a numerical variable into a properly formatted string. After all, a string like 1,234.56 is easier to read than 1234.56.
use Punic\Number;
echo Number::format(1234.567, 2, 'it');
// Output: 1.234,57
echo Number::format(1234.567, 2, 'en');
// Output: 1,234.57
echo Number::unformat('1.234,56', 'it');
// Output: 1234.56
echo Number::unformat('1,234.56', 'en');
// Output: 1234.56
Punic\Phone
class¶
Need to know the country calling codes of a country? Need to know the countries associated to a country calling code? Use this class!
use Punic\Phone;
var_export(Phone::getPrefixesForTerritory('US'));
// Output: an array containing '1', the country calling code for US
var_export(Phone::getTerritoriesForPrefix('1'));
// Output: an array containing the country codes having '1' as country calling code
// (for instance US, CA)
Punic\Plural
class¶
Need to know the plural of a number? Use this class.
use Punic\Plural;
echo Plural::getRule(1, 'en');
// Output: one
echo Plural::getRule(2, 'en');
// Output: other
Punic\Territory
class¶
The territory class contains several methods to work with regions, countries and continents.
use Punic\Territory;
echo Territory::getName('US', 'en');
// Output: United States
$countries = Territory::getCountries();
print_r($countries);
// Output: the list of all countries, indexed by the territory code
$continents = Territory::getContinents();
print_r($continents);
// Output: the list of all continents
$continentsAndCountries = Territory::getContinentsAndCountries();
print_r($continentsAndCountries);
// Output: the list of all countries grouped by continent
Punic\Unit
class¶
Whether you need an abbreviation or a long form of a number with a unit, use this class. Properly formatted numbers and units in every the language.
use Punic\Unit;
echo Unit::format(2.0123, 'millisecond', 2, 'it');
// Output: 2,01 ms
echo Unit::format(2.0123, 'millisecond', 'long,1', 'it');
// Output: 2,0 millisecondi
echo Unit::format(2.0123, 'millisecond', 'narrow', 'it');
// Output: 2,0123 ms
Language Data¶
To keep the size of the package at a reasonable level, only data for a limited set of languages (about 40, defined here) is included by default. If you need more, you can get them yourself using the bundled punic-data script.
To get help about how to run this command:
./bin/punic-data --help
(On Windows, use \
instead of /
)
Please remark that when you upgrade your locally installed Punic with Composer, the language files are reverted to the default ones. In the case you want to be sure that you have the languages you need even after Punic is upgraded (for instance, af and zu_ZA), you can add this section to your composer.json file:
"scripts": {
"post-install-cmd": [
"punic-data --locale=+af,+zu_ZA"
],
"post-update-cmd": [
"punic-data --locale=+af,+zu_ZA"
]
}
Language data is fetched from a remote repository.
If you plan to install many languages on a regular basis, you can also evaluate to use a local language repository,
fetching this repository and instructing punic-data
to use it with the --source-location
option.
The default data used by Punic is the one generated by punic/data. You can clone it and use it as the data source.