arraypress / wp-countries
A lightweight WordPress library for working with country codes and names with translation support.
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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(namespaceSugarCommerce\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'si18n/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.