README

GlobalCountries is the most complete, performant, and exhaustive country information package for the PHP ecosystem. It provides everything you need to build world-class global applications, featuring deeply detailed metadata for every country and territory on Earth.

📖 Table of Contents

• ✨ Features
• 🚀 Installation
• 💡 Quick Start
• 🔥 Pro Tips & Advanced Usage
• 🔍 Searching & Filtering
• 🗺️ Exhaustive Data Model
• 🌍 Localization
• 📱 Phone Number Intelligence
• 🏗️ Laravel Integration
• 📊 Performance
• 🎨 Frontend & UI Utilities
• 🤝 Contributing

✨ Features

• 🚀 Extreme Performance: Data is pre-compiled into optimized PHP arrays for near-instant access.
• 📦 Exhaustive Metadata: Deep details including population, GDP, Gini index, postal formats, and more.
• 🎨 Visual Assets: SVG/PNG flags, Emoji support, and Coat of Arms (SVG/PNG).
• 🌍 Localization: Multilingual support for country names and native scripts.
• 🔍 Fluent API: Powerful searching, filtering, and sorting with a "magical" interface.
• 🏗️ Framework Agnostic: Works perfectly in Vanilla PHP, Laravel, Symfony, and WordPress.
• 🎨 Laravel Ready: Includes Service Provider, Facades, Validation Rules, and Blade Components.

🚀 Installation

Clone this repository or include it in your project:

git clone https://github.com/mutebesi/Global-Countries-PHP.git

If using Composer:

composer require mutebesi/globalcountries

💡 Quick Start

use GlobalCountries\Countries;

// Get all countries
$countries = Countries::all();

// Find a specific country by ISO code (Alpha-2, Alpha-3, or Numeric)
$kenya = Countries::find('KE');

echo $kenya->name;         // Kenya
echo $kenya->capital;      // Nairobi
echo $kenya->population;   // 53771300
echo $kenya->flagEmoji();  // 🇰🇪

🔥 Pro Tips & Advanced Usage

Make your code feel like magic with our advanced fluent API:

// 1. One-liner to get all African country names joined by commas
echo Countries::whereContinent('Africa')->sortBy('name')->join(', ');

// 2. Pluck specific fields as an associative array [iso2 => callingCode]
$dialCodes = Countries::whereContinent('Europe')->pluck('callingCode', 'iso2');

// 3. Filter countries by population threshold
$giants = Countries::wherePopulationAbove(100000000); // 100M+

// 4. Guess country from phone and get its currency symbol instantly
echo Countries::guessFromPhone('+254712345678')->currencySymbol(); // KSh

// 5. Group by continent and get the count for each
foreach (Countries::all()->groupBy('continent') as $continent => $group) {
    echo "{$continent}: {$group->count()} countries";
}

🔍 Searching & Filtering

// Filter by continent
$africa = Countries::whereContinent('Africa');

// Filter by language (ISO 639-2 or 639-1)
$spanishSpeaking = Countries::whereLanguage('spa');

// Get all EU member states
$eu = Countries::eu();

// Search by name or code (fuzzy search)
$results = Countries::search('United');

// Sorting
$sorted = Countries::all()->sortBy('population');

🗺️ Exhaustive Data Model

Each Country object is an immutable DTO containing premium metadata:

Basic Information

• $country->name: Common name (e.g., "Kenya")
• $country->officialName: Official name (e.g., "Republic of Kenya")
• $country->nativeNames: Native names keyed by language code.
• $country->iso2, $country->iso3, $country->isoNumeric: ISO 3166-1 codes.
• $country->ioc, $country->fifa: Sports organization codes.
• $country->slug: URL-friendly identifier (e.g., "ke").

Geography

• $country->continent, $country->region, $country->subregion.
• $country->latlng: [latitude, longitude].
• $country->area: Total area in km².
• $country->borders: Neighboring country ISO-3 codes.
• $country->isLandlocked: Boolean status.

Political & Demographics

• $country->capital: Capital city name.
• $country->capitalLatLng: Coordinates of the capital city.
• $country->population: Total population count.
• $country->status: Sovereignty status.
• $country->isUnMember, $country->isIndependent.

Communication & Visuals

• $country->callingCode: International prefix (e.g., "+254").
• $country->flagEmoji, $country->flagSvg, $country->flagPng.
• $country->coatOfArms: Coat of Arms (SVG/PNG URL).

Economics & Technical

• $country->currencyCode(), $country->currencySymbol(), $country->currencyName().
• $country->gdp: Gross Domestic Product.
• $country->gini: Gini index of income inequality.
• $country->postalCodeFormat(), $country->postalCodeRegex().
• $country->tlds: Internet domains.
• $country->drivingSide: "left" or "right".
• $country->timezones: Supported timezones.
• $country->startOfWeek: e.g., "monday".

🏗️ Laravel Integration

Validation Rule

use Illuminate\Validation\Rule;

$request->validate([
    'country_code' => ['required', Rule::country()],
]);

Blade Component

<x-country-select name="country" selected="KE" class="custom-select" />

📊 Performance

🎨 Frontend & UI Utilities

// Generate practical HTML selects with flags and grouping
foreach (Countries::all()->sortBy('name') as $country) {
    echo "<option value='{$country->iso2}'>{$country->flagEmoji} {$country->name}</option>";
}

🤝 Contributing

Please see CONTRIBUTING.md for details.

📄 License

The MIT License (MIT). Please see License File for more information.