Skip to content

Getting started

Requirements

  • PHP 8.4+ with the intl extension (php -m | grep intl).

Install

composer require salarmehr/cosmopolitan

Package name vs namespace

For a smooth v2 → v3 upgrade the Composer package keeps its long-standing name salarmehr/cosmopolitan; only the namespace rebrands to Miloun\Cosmo. Existing users bump the constraint to ^3.0 and run a Salarmehr\Cosmopolitan → Miloun\Cosmo find/replace.

Quick start

Construct with a locale (and an optional time zone, calendar, or currency modifier), then call methods on it. New to these codes? See Locales & time zones.

use Miloun\Cosmo\Cosmo;

$c = new Cosmo('en_AU', ['timeZone' => 'Australia/Sydney']);

$c->country();          // "Australia"
$c->money(1234.5);      // "$1,234.50"  (currency inferred from region)
$c->number(1234567.89); // "1,234,567.89"
$c->flag();             // "🇦🇺"

PHP 8.4 lets you call a method directly on new Cosmo(...) without wrapping parentheses, or use the cosmo() helper: cosmo('en_AU')->country().

Locale format

Underscore locales (en_AU) and BCP-47 tags (en-AU), including Unicode extensions like fa-IR-u-nu-latn-ca-buddhist, are supported. Use hyphens in locale tags, such as en-AU. See Locales & time zones for the format explained and how to find yours.

Constructing without a string

Build a locale from subtags or an HTTP Accept-Language header:

Cosmo::fromSubtags(['language' => 'en', 'region' => 'AU']);
Cosmo::fromAcceptLanguage($_SERVER['HTTP_ACCEPT_LANGUAGE']);

Migrating existing localisation code

If your app already has custom formatting helpers or locale tables, you can use this prompt with a coding assistant that has access to your project:

Migrate this project's custom localisation code to Cosmo.

Read https://cosmo.miloun.com/php/getting-started/ and
https://cosmo.miloun.com/php/api-reference/. Check
https://cosmo.miloun.com/php/platform-notes/ for runtime limitations.

Inspect the project to identify its language, runtime versions, locale and
time-zone settings, and existing localisation helpers. Find custom code for
number, currency, date, time, unit, list, plural, and text formatting, along
with any hardcoded locale data that Cosmo can replace.

Install the appropriate Cosmo package and migrate supported operations using
the documented API for this language. Reuse the app's locale, time zone,
calendar, and currency settings. Keep business rules, currency conversion,
and translation catalogue management in place unless a documented Cosmo
feature covers the existing behaviour.

Preserve public interfaces where practical. Check timestamp units, rounding,
currency precision, plural rules, and error handling at each migrated call
site. If ICU formatting changes the displayed output, explain the difference
rather than assuming it is equivalent. Keep unsupported operations working
and identify why they could not be migrated.

Update or add tests for representative supported locales and important edge
cases, then run the relevant checks. Remove obsolete helpers and locale tables
once their callers have been migrated. Summarise the changes, output differences,
and any remaining custom localisation code.

Review the resulting changes, especially where existing output is part of a public API or an exact string comparison. Locale conventions and ICU versions can affect spacing, punctuation, and wording.

Ready for the details? Head to the Guide.