Getting started

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 found in the zip.

Installation using composer

As Punic is written using PSR-4, it's highly recommended to use composer to use it. Begin by editing your project's composer.json to require punic/punic.

"require": {
    "punic/punic": "3.*"

Next, go to your favourite terminal and run composer update.

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.

Main classes

Here's the list of the main classes that you may want to use in your projects:

  • Punic/Data To set the default locale, so that you don't need to specify it every you use Punic functions.
  • Punic/Calendar To work with dates
  • Punic/Language To work with languages.
  • Punic/Territory To work with countries and continents.
  • Punic/Number Number-related functions.
  • Punic/Unit To work with units (acceleration, angles, area, duration, distance, volume… too many to list them!).
  • Punic/Misc Miscellaneous functions (lists, case, …).
  • Punic/Plural It's mainly for internal use, but you may want to use it.
  • Punic/Phone To work with phone numbers.
  • Punic/Currency To work with currencies.

Language support

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:

<Path/to/Punic>/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 bin/punic-data to use it with the --source-location option.


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.


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.


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.


The territory class contains several methods to work with regions, countries and continents.


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.


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 the misc class to join a list of numbers correctly into a single string.


Need to know the plural of a number, use this 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!


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!