Search by

arraypress / wp-countries

arraypress

A lightweight WordPress library for working with country codes and names with translation support.

Package info

github.com/arraypress/wp-countries

pkg:composer/arraypress/wp-countries

Statistics

Installs: 885

Dependents: 5

Suggesters: 1

Stars: 0

Open Issues: 0

v1.0.0 2026-08-25 17:48 UTC

This package is auto-updated.

Last update: 2026-11-18 10:51:04 UTC


README

This library has moved. It is now part of sugarcommerce/geo (namespace SugarCommerce\Geo, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.

WordPress Countries

Country codes, names and continents, with the groupings a shop actually needs.

What it does

Every store form needs a country dropdown, and every stored order needs a two-letter code turned back into a name. Beyond that it is always the same questions: is this in the EU for VAT, which continent is it, and is it on the list we treat with more caution.

Names go through WordPress translation, so the dropdown follows the site language rather than being English-only.

Features

  • Look up a country name from its code, and a code from its name
  • Build a ready-made options array for a <select>
  • Look up the states or provinces of a country, for a dependent dropdown
  • Write an address in its country's order, and ask what the country calls its region and its postcode -- or whether it has one
  • Search by partial name, for an autocomplete
  • Check EU membership, for VAT decisions
  • Group by continent, or ask which continent a country is in
  • Flag a country as higher risk, for fraud rules
  • Get the flag emoji for a code, or a flag that looks the same on every machine: a bundled SVG, as a URL or an <img>
  • Sanitise a user-supplied code down to a real one, or null

Installation

composer require arraypress/wp-countries

Quick start

use ArrayPress\Countries\Countries;
use ArrayPress\Countries\Regions;

// A country dropdown.
foreach ( Countries::all() as $code => $name ) {
    printf( '<option value="%s">%s</option>', esc_attr( $code ), esc_html( $name ) );
}

// The provinces for the country picked, for a dependent dropdown.
$regions = Regions::for( 'CA' );  // [ 'AB' => 'Alberta', 'BC' => 'British Columbia', ... ]

// Turn a stored code back into something readable.
echo esc_html( Countries::get_name( $order->billing_country ) );  // United Kingdom

// VAT applies?
if ( Countries::is_eu( $order->billing_country ) ) {
    // ...
}

// Never trust a posted code.
$code = Countries::sanitize( $_POST['country'] ?? '' );

Flags

An emoji flag is drawn by whatever the reader's machine has, and on Windows that is the two letters and no picture. Flags gives the same country as a file that ships with the library -- 265 of them, in assets/flags:

use ArrayPress\Countries\Flags;

Flags::url( 'GB' );   // https://example.com/wp-content/plugins/your-plugin/vendor/arraypress/wp-countries/assets/flags/gb.svg
Flags::img( 'gb' );   // <img class="country-flag" src="…/gb.svg" width="16" height="16" alt="" loading="lazy" decoding="async" />
Flags::img( 'GB', 24, [ 'class' => 'my-flag', 'alt' => 'United Kingdom' ] );
Flags::exists( 'zz' ); // false

A code is two letters and nothing else; anything that is not, or has no file, is an empty string. The URL is worked out from where the library is installed -- vendor/, a Strauss-prefixed copy, a checkout beside the plugins, a symlinked plugin -- and nothing is fetched from anywhere else. To serve the files from somewhere of your own, or to say where they are when the library sits outside the web root:

add_filter( 'arraypress_countries_flags_url', fn() => 'https://cdn.example.com/flags/' );

The pictures are circle-flags by HatScripts, MIT licensed; the licence is beside them. If you build with Strauss, the assets folder is copied with the rest of the package and needs nothing set.

Addresses

use ArrayPress\Countries\Addresses;

// The lines of an address, in the order the country writes them.
Addresses::format( [
    'line1'    => '500 Congress Ave',
    'city'     => 'Austin',
    'state'    => 'TX',          // a code from Regions, or whatever was typed
    'postcode' => '78701',
    'country'  => 'US',
] );
// [ '500 Congress Ave', 'Austin, TX 78701' ]

// Germany puts the postcode first and has no place for a state.
// [ 'Hauptstraße 1', '10115 Berlin' ]

// What to call the boxes on a form, and which to show.
Addresses::get_labels( 'US' );  // [ 'city' => 'City', 'state' => 'State', 'postcode' => 'ZIP code' ]
Addresses::get_labels( 'GB' );  // [ 'city' => 'Town or city', 'state' => 'County', 'postcode' => 'Postcode' ]
Addresses::get_parts( 'HK' );   // [ 'city' => true, 'state' => true, 'postcode' => false ]
Addresses::get_types( 'JP' );   // [ 'city' => 'city', 'state' => 'prefecture', 'postcode' => 'postal' ]

// Before a country is chosen, the general words.
Addresses::get_labels( '' );    // [ 'city' => 'Town or city', 'state' => 'State, county or region', 'postcode' => 'Postcode or ZIP' ]

// Everything a form needs to follow its country, ready to hand to a script.
Addresses::get_fields( 'GB' );
// [ 'city' => 'Town or city', 'state' => 'County', 'postcode' => 'Postcode',
//   'has_city' => true, 'has_state' => true, 'has_postcode' => true,
//   'has_states' => false ]   // a county is typed: there is no list to choose from

The labels are translated, in the arraypress text domain. A plugin that bundles the library and re-domains library strings at build time gets them in its own language file. A caller with wording of its own keys off get_types().

To rename and hide the boxes of a form as its country changes, send the script get_fields( '' ) as the fallback and only the countries that differ from it (most countries call their postcode a postal code, so the saving is large):

$fallback  = Addresses::get_fields( '' );
$countries = [];

foreach ( array_keys( Countries::all() ) as $code ) {
    $different = array_diff_assoc( Addresses::get_fields( $code ), $fallback );

    if ( [] !== $different ) {
        $countries[ $code ] = $different;
    }
}

The parts an address can have are name, company, line1, line2, city, state, postcode and country, all optional. A part with nothing in it takes its punctuation with it; a part the country does not write (a state on a German address) is left out. Pass true as the second argument to end with the country's name.

A region is printed as its code where the country writes it that way (the United States, Canada, Australia, Brazil, Italy) and as its name elsewhere. Japan, China, Korea and a few others are written largest-first when any part is in their own script and smallest-first in Latin letters.

The formats are generated from the address metadata behind Google's libaddressinput, which is licensed CC-BY 4.0. bin/generate-address-formats.php says what is taken and the two places it is added to (a county line for the United Kingdom, a city for Japan).

Requirements

  • PHP 8.3 or later
  • WordPress 7.1 or later

License

The library is GPL-3.0-or-later. Three things in it are somebody else's, each under its own licence:

  • src/Regions.php -- the subdivision table follows WooCommerce's i18n/states.php, and WooCommerce is GPL-3.0-or-later, which is why this library is too.
  • src/AddressFormats.php -- the address table is generated from Google's libaddressinput metadata, CC-BY 4.0; the file's header is the attribution.
  • assets/flags/ -- circle-flags by HatScripts, MIT; the licence is in the folder.