README

A lightweight WordPress library for working with countries, regions, and continents. Provides clean APIs for location operations, validation, flag emojis, and value/label formatting perfect for forms and admin interfaces.

Features

🌍 Complete Geographic Data: Countries, regions/states, and continents
🎯 Clean API: WordPress-style snake_case methods with consistent interfaces
🏴 Flag Emojis: Full flag emoji support for all countries
🔍 Built-in Search: Location search with value/label formatting
📋 Form-Ready Options: Perfect value/label arrays for selects and forms
🌳 Hierarchical Support: Grouped options for countries and regions
✅ Validation: Easy validation for country codes, regions, and continents
🔗 Relationships: Find countries by continent, regions by country, etc.
🎨 Flexible Formats: Support for key/value and value/label option formats
🗺️ Geographic Features: Island nations, English-speaking countries, etc.

Requirements

PHP 7.4 or later
WordPress 5.0 or later

Installation

composer require arraypress/wp-location-utils

Basic Usage

Working with Countries

use ArrayPress\LocationUtils\Country;

// Get country name by code
$name = Country::get_name( 'US' ); // "United States (US)"

// Check if country exists
if ( Country::exists( 'US' ) ) {
	// Country exists
}

// Get continent for country
$continent = Country::get_continent( 'US' ); // "NA"

// Check if country is in continent
if ( Country::is_in_continent( 'US', 'NA' ) ) {
	// US is in North America
}

// Get regions for country
$regions = Country::get_regions( 'US' ); // Array of US states

// Check if country has regions
if ( Country::has_regions( 'US' ) ) {
	// US has states
}

Working with Regions

use ArrayPress\LocationUtils\Region;

// Get region name by code
$name = Region::get_name( 'CA' ); // May return "California" or "Canada" depending on context
$name = Region::get_name( 'CA', 'US' ); // "California" (when country specified)

// Check if region exists
if ( Region::exists( 'CA', 'US' ) ) {
	// California exists in US
}

// Get regions for a country
$us_states = Region::get_by_country( 'US' );

// Get country for a region
$country = Region::get_country( 'CA' ); // May return "US" or "CA" depending on context

// Check if region represents all regions
if ( Region::is_all_regions( 'all' ) ) {
	// Represents all regions
}

Working with Continents

use ArrayPress\LocationUtils\Continent;

// Get continent name by code
$name = Continent::get_name( 'NA' ); // "North America"

// Check if continent exists
if ( Continent::exists( 'NA' ) ) {
	// North America exists
}

// Get countries in continent
$countries = Continent::get_countries( 'NA' ); // Array of country codes

// Check if continent has country
if ( Continent::has_country( 'NA', 'US' ) ) {
	// North America has US
}

Working with Flag Emojis

use ArrayPress\LocationUtils\Flag;

// Get flag emoji for country
$flag    = Flag::get_emoji( 'US' ); // 🇺🇸
$uk_flag = Flag::get_emoji( 'GB' ); // 🇬🇧

// Get country name with flag
$us_with_flag = Flag::get_name_with_flag( 'US' ); // "🇺🇸 United States (US)"
$uk_name_flag = Flag::get_name_with_flag( 'GB', 'name_flag' ); // "United Kingdom (UK) 🇬🇧"
$flag_only    = Flag::get_name_with_flag( 'US', 'flag_only' ); // "🇺🇸"

// Check if country has flag emoji
if ( Flag::has_flag( 'US' ) ) {
	// US has a flag emoji
}

// Get all countries with flags
$countries_with_flags = Flag::get_countries_with_flags();
// Returns: ['US' => '🇺🇸 United States (US)', 'GB' => '🇬🇧 United Kingdom (UK)', ...]

// Get flag options for forms
$flag_options = Flag::get_options_with_flags();
// Returns: [['value' => 'US', 'label' => '🇺🇸 United States (US)'], ...]

// Search countries with flags
$search_results = Flag::search_with_flags( 'united' );
// Returns: ['US' => '🇺🇸 United States (US)', 'GB' => '🇬🇧 United Kingdom (UK)', ...]

// Get HTML entities (for database storage)
$html_flag = Flag::get_html_entity( 'US' ); // "&#127482;&#127480;"

Validation and Geographic Features

use ArrayPress\LocationUtils\Validate;

// Basic validation
$is_valid_country   = Validate::location( 'US', 'country' );
$is_valid_region    = Validate::location( 'CA', 'region' );
$is_valid_continent = Validate::location( 'NA', 'continent' );

// Validate region in country
$is_ca_in_us = Validate::region_in_country( 'CA', 'US' ); // true (California in US)

// Continent checks
$is_european       = Validate::is_eu( 'DE' ); // true (Germany is in Europe)
$is_asian          = Validate::is_asia( 'JP' ); // true (Japan is in Asia)
$is_north_american = Validate::is_north_america( 'US' ); // true
$is_south_american = Validate::is_south_america( 'BR' ); // true (Brazil)
$is_african        = Validate::is_africa( 'NG' ); // true (Nigeria)
$is_oceanic        = Validate::is_oceania( 'AU' ); // true (Australia)

// Geographic feature checks
$has_states = Validate::has_regions( 'US' ); // true (US has states)
$is_english = Validate::is_english_speaking( 'GB' ); // true
$is_island  = Validate::is_island_nation( 'JP' ); // true

Search Functionality

// Search countries
$countries = Country::search( 'united' );
// Returns: ['US' => 'United States (US)', 'GB' => 'United Kingdom (UK)', ...]

// Search and get value/label options
$options = Country::search_options( 'united' );
// Returns: [['value' => 'US', 'label' => 'United States (US)'], ...]

// Search regions
$regions        = Region::search( 'new', 'US' ); // Search US states for "new"
$region_options = Region::search_options( 'new', 'US' );

// Search continents
$continents        = Continent::search( 'america' );
$continent_options = Continent::search_options( 'america' );

Form Options

// Get country options for forms
$country_options = Country::get_options();
// Returns: ['US' => 'United States (US)', 'CA' => 'Canada', ...]

// Get value/label format
$country_options = Country::get_value_label_options();
// Returns: [['value' => 'US', 'label' => 'United States (US)'], ...]

// Filter by continent
$eu_countries = Country::get_options( [ 'continent' => 'EU' ] );

// Get region options
$us_states   = Region::get_options( 'US' );
$all_regions = Region::get_options(); // All regions from all countries

// Get grouped location options (for hierarchical dropdowns)
$grouped = Region::get_grouped_options();
// Returns grouped structure perfect for optgroup selects

// Get continent options
$continents = Continent::get_options();

Parsing Location Strings

use ArrayPress\LocationUtils\Parse;

// Parse location strings
$parsed = Parse::location_string( 'US_CA' );
// Returns: ['country' => 'US', 'region' => 'CA', 'is_all' => false]

$parsed = Parse::location_string( 'US_all' );
// Returns: ['country' => 'US', 'region' => '', 'is_all' => true]

// Build location strings
$location = Parse::build_location_string( 'US', 'CA' ); // "US_CA"
$location = Parse::build_location_string( 'US', '', true ); // "US_all"

Utility Functions

use ArrayPress\LocationUtils\Utils;

// Convert between formats
$value_label = Utils::to_value_label( [ 'US' => 'United States' ] );
$key_value   = Utils::from_value_label( $value_label );

Advanced Usage

Country Dropdowns with Flags

// Simple dropdown with flags
$countries = Flag::get_options_with_flags();
foreach ( $countries as $country ) {
	echo '<option value="' . esc_attr( $country['value'] ) . '">';
	echo esc_html( $country['label'] );
	echo '</option>';
}

// Continent-specific countries with flags
$eu_flags    = Flag::get_continent_countries_with_flags( 'EU' );
$asian_flags = Flag::get_continent_countries_with_flags( 'AS' );

// Different flag formats
$flag_first = Flag::get_options_with_flags( [ 'format' => 'flag_name' ] );
$flag_last  = Flag::get_options_with_flags( [ 'format' => 'name_flag' ] );
$flags_only = Flag::get_options_with_flags( [ 'format' => 'flag_only' ] );

Custom Validation

// Validate multiple location types
function validate_location( $code, $type = 'country' ) {
	return Validate::location( $code, $type );
}

// Complex geographic validation
function is_english_speaking_island( $country_code ) {
	return Validate::is_english_speaking( $country_code ) &&
	       Validate::is_island_nation( $country_code );
}

// Validate location relationships
function validate_region_in_country( $region_code, $country_code ) {
	return Validate::region_in_country( $region_code, $country_code );
}

Dynamic Form Building

// Build dynamic country/region selects
function get_location_select_data( $country_code = '' ) {
	$data = [
		'countries' => Country::get_value_label_options(),
		'regions'   => []
	];

	if ( ! empty( $country_code ) ) {
		$data['regions'] = Region::get_value_label_options( $country_code );
	}

	return $data;
}

// AJAX endpoint for dynamic region loading
function ajax_get_regions() {
	$country_code = $_POST['country'] ?? '';
	if ( Country::exists( $country_code ) ) {
		wp_send_json_success( Region::get_value_label_options( $country_code ) );
	}
	wp_send_json_error( 'Invalid country' );
}

// Get regions with flags (if applicable)
function get_regions_with_context( $country_code ) {
	$regions      = Region::get_by_country( $country_code );
	$country_flag = Flag::get_emoji( $country_code );
	$country_name = Country::get_name( $country_code );

	return [
		'country' => [
			'code' => $country_code,
			'name' => $country_name,
			'flag' => $country_flag
		],
		'regions' => $regions
	];
}

Geographic Analysis

// Analyze geographic distribution
function analyze_user_countries( $user_countries ) {
	$analysis = [
		'continents'       => [],
		'english_speaking' => 0,
		'island_nations'   => 0,
		'total'            => count( $user_countries )
	];

	foreach ( $user_countries as $country_code ) {
		// Count by continent
		$continent                            = Country::get_continent( $country_code );
		$analysis['continents'][ $continent ] = ( $analysis['continents'][ $continent ] ?? 0 ) + 1;

		// Count special features
		if ( Validate::is_english_speaking( $country_code ) ) {
			$analysis['english_speaking'] ++;
		}

		if ( Validate::is_island_nation( $country_code ) ) {
			$analysis['island_nations'] ++;
		}
	}

	return $analysis;
}

// Get countries by special criteria
$english_islands = [];
$all_countries   = Country::get_options();

foreach ( array_keys( $all_countries ) as $country_code ) {
	if ( Validate::is_english_speaking( $country_code ) &&
	     Validate::is_island_nation( $country_code ) ) {
		$english_islands[ $country_code ] = Flag::get_name_with_flag( $country_code );
	}
}
// Results: Australia 🇦🇺, New Zealand 🇳🇿, United Kingdom 🇬🇧, Ireland 🇮🇪, etc.

Database Storage Considerations

// For databases that don't support emoji
function store_country_with_flag( $country_code ) {
	return [
		'code'       => $country_code,
		'name'       => Country::get_name( $country_code ),
		'flag_emoji' => Flag::get_emoji( $country_code ),
		'flag_html'  => Flag::get_html_entity( $country_code ),
		'continent'  => Country::get_continent( $country_code )
	];
}

// Display with fallback
function display_country_flag( $country_code ) {
	$flag = Flag::get_emoji( $country_code );
	if ( empty( $flag ) ) {
		// Fallback to text representation
		return '[' . $country_code . ']';
	}

	return $flag;
}

Filtering and Customization

All data can be customized using WordPress filters:

// Customize country list
add_filter( 'location_utils_countries', function ( $countries ) {
	// Add custom country or modify existing
	$countries['XX'] = 'Custom Country';

	return $countries;
} );

// Customize regions
add_filter( 'location_utils_regions', function ( $regions ) {
	// Add custom regions for a country
	$regions['XX'] = [ 'XX-01' => 'Custom Region' ];

	return $regions;
} );

// Customize continents
add_filter( 'location_utils_continents', function ( $continents ) {
	// Modify continent data
	return $continents;
} );

// Customize flag display
add_filter( 'location_utils_flag_format', function ( $format, $country_code ) {
	// Custom flag formatting logic
	return $format;
}, 10, 2 );

API Reference

Country Class Methods

get_name( $code ) - Get country name by code
exists( $code ) - Check if country exists
get_continent( $country_code ) - Get continent for country
is_in_continent( $country_code, $continent_code ) - Check if country is in continent
get_regions( $country_code ) - Get regions for country
has_regions( $country_code ) - Check if country has regions
search( $search ) - Search countries by name
search_options( $search ) - Search countries and return value/label format
get_options( $args ) - Get country options for forms
get_value_label_options( $args ) - Get country options in value/label format

Region Class Methods

get_name( $region_code, $country_code ) - Get region name by code
exists( $region_code, $country_code ) - Check if region exists
get_by_country( $country_code ) - Get regions for country
get_country( $region_code ) - Get country for region
is_all_regions( $region ) - Check if represents all regions
search( $search, $country_code ) - Search regions
search_options( $search, $country_code ) - Search regions in value/label format
get_options( $country_code, $args ) - Get region options
get_value_label_options( $country_code, $args ) - Get region options in value/label format
get_grouped_options( $args ) - Get hierarchical location options

Continent Class Methods

get_name( $code ) - Get continent name by code
exists( $code ) - Check if continent exists
get_countries( $continent_code ) - Get countries in continent
has_country( $continent_code, $country_code ) - Check if continent has country
search( $search ) - Search continents
search_options( $search ) - Search continents in value/label format
get_options( $args ) - Get continent options
get_value_label_options( $args ) - Get continent options in value/label format

Flag Class Methods

get_emoji( $country_code ) - Get flag emoji for country
get_name_with_flag( $country_code, $format ) - Get country name with flag
get_countries_with_flags( $format ) - Get all countries with flags
get_options_with_flags( $args ) - Get country options with flags for forms
has_flag( $country_code ) - Check if country has flag emoji
get_html_entity( $country_code ) - Get flag as HTML entity
search_with_flags( $search, $format ) - Search countries with flags
get_continent_countries_with_flags( $continent_code, $format ) - Get continent countries with flags

Validate Class Methods

location( $code, $type ) - Validate location by type
region_in_country( $region_code, $country_code ) - Validate region in country
is_eu( $country_code ) - Check if country is in Europe
is_asia( $country_code ) - Check if country is in Asia
is_north_america( $country_code ) - Check if country is in North America
is_south_america( $country_code ) - Check if country is in South America
is_africa( $country_code ) - Check if country is in Africa
is_oceania( $country_code ) - Check if country is in Oceania
has_regions( $country_code ) - Check if country has regions
is_english_speaking( $country_code ) - Check if major English-speaking country
is_island_nation( $country_code ) - Check if island nation

Parse Class Methods

location_string( $location_string ) - Parse compound location string
build_location_string( $country_code, $region_code, $is_all ) - Build location string

Utils Class Methods

to_value_label( $options ) - Convert key/value to value/label format
from_value_label( $options ) - Convert value/label to key/value format

Key Features

Flag Emoji Support: Full Unicode flag emoji support for all countries
Value/Label Format: Perfect for modern form libraries and APIs
Hierarchical Support: Built-in support for country > region relationships
Search Functionality: Fast searching across all location types
Validation: Comprehensive validation for all location types
Geographic Features: Special validation for island nations, English-speaking countries, etc.
Flexible Options: Multiple formats for different use cases
WordPress Integration: Follows WordPress coding standards and patterns
Database Compatibility: HTML entity support for databases without emoji support

Browser Support

✅ Flag emojis work in all modern browsers
✅ Mobile devices (iOS, Android)
✅ Desktop OS (Windows 10+, macOS, Linux)
✅ Fallback options for unsupported systems

Requirements

PHP 7.4+
WordPress 5.0+
utf8mb4 database charset (for flag emoji storage)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

arraypress / wp-location-utils

Maintainers

Details

README

Features

Requirements

Installation

Basic Usage

Working with Countries

Working with Regions

Working with Continents

Working with Flag Emojis

Validation and Geographic Features

Search Functionality

Form Options

Parsing Location Strings

Utility Functions

Advanced Usage

Country Dropdowns with Flags

Custom Validation

Dynamic Form Building

Geographic Analysis

Database Storage Considerations

Filtering and Customization

API Reference

Country Class Methods

Region Class Methods

Continent Class Methods

Flag Class Methods

Validate Class Methods

Parse Class Methods

Utils Class Methods

Key Features

Browser Support

Requirements

Contributing

License

Support