README

Framework-agnostic access to world countries and ISO 3166-2 regions/subdivisions from bundled JSON datasets.

Maintained by OctaCrafts.

No database. No external API. No runtime downloads. Everything works entirely from local JSON files shipped with the package.

About OctaCrafts

OctaCrafts is a global IT systems and software engineering company that builds scalable digital ecosystems for businesses worldwide. From idea to launch, the team delivers enterprise-grade solutions focused on long-term growth, performance, and reliability.

What we do:

Web Development & Design — modern, responsive, high-performance websites
SaaS & ERP Solutions — custom platforms that automate workflows and centralize operations
Mobile Apps Development — scalable Android, iOS, and cross-platform applications
DevOps & Deployment — secure cloud infrastructure, automation, and monitoring
Web Maintenance — ongoing security updates, backups, and technical support
Infographics & Motion Graphics — visual content and animations for clear communication

Beyond client projects, OctaCrafts maintains open-source PHP libraries under the oc/* package family on GitHub @octacrafts. Each ecosystem follows a core-plus-wrapper pattern: framework-agnostic cores for plain PHP and any PSR-compliant app, with dedicated integrations for popular frameworks.

oc/world-countries is the framework-agnostic core for country and region data. For Laravel projects, use oc-world-countries-laravel. Symfony and other framework wrappers are planned.

Requirements

PHP 8.2+
ext-json
ext-mbstring

Installation

composer require oc/world-countries

Quick Start

use Oc\WorldCountries\WorldCountries;

$world = new WorldCountries();

$pakistan = $world->country('PK');
$regions = $world->regions('PK');
$punjab = $world->region('PK', 'PB');

Usage Examples

Countries

$world = new WorldCountries();

// Find by ISO 3166-1 alpha-2
$pakistan = $world->country('PK');

// Find by ISO 3166-1 alpha-3
$pakistan = $world->countryByAlpha3('PAK');

// Check existence (alpha-2 or alpha-3)
$exists = $world->hasCountry('pak');

// Get all countries
$countries = $world->countries();

// Search countries (case-insensitive, partial match)
$results = $world->searchCountries('pak');

// Build dropdown options: ['PK' => 'Pakistan', ...]
$options = $world->countryOptions();

Regions

// Get all regions for a country (alpha-2 or alpha-3)
$regions = $world->regions('PK');
$regions = $world->regions('PAK');

// Find a specific region
$punjab = $world->region('PK', 'PB');

// Check region existence
$exists = $world->hasRegion('PK', 'PB');

// Search regions within a country
$results = $world->searchRegions('PK', 'pun');

// Build dropdown options: ['PB' => 'Punjab', ...]
$options = $world->regionOptions('PK');

API Reference

`WorldCountries`

Method	Return Type	Description
`countries()`	`list<Country>`	All countries
`country(string $alpha2)`	`?Country`	Find country by alpha-2 code
`countryByAlpha3(string $alpha3)`	`?Country`	Find country by alpha-3 code
`hasCountry(string $code)`	`bool`	Check if country exists (alpha-2 or alpha-3)
`regions(string $countryCode)`	`list<Region>`	All regions for a country
`region(string $countryCode, string $regionCode)`	`?Region`	Find a specific region
`hasRegion(string $countryCode, string $regionCode)`	`bool`	Check if region exists
`searchCountries(string $query)`	`list<Country>`	Search countries by name or code
`searchRegions(string $countryCode, string $query)`	`list<Region>`	Search regions by name or code
`countryOptions()`	`array<string, string>`	Alpha-2 code to country name map
`regionOptions(string $countryCode)`	`array<string, string>`	Region code to region name map

DTOs

All public methods return typed, immutable DTOs — never raw JSON arrays.

Oc\WorldCountries\DTOs\Country

string $alpha2
string $alpha3
string $name
string $numeric
?string $flag

Oc\WorldCountries\DTOs\Region

string $countryAlpha2
string $countryAlpha3
string $code
string $name
string $type

Advanced Usage

The package uses constructor dependency injection with sensible defaults. You can inject custom repository implementations for testing or framework wrappers:

use Oc\WorldCountries\WorldCountries;
use Oc\WorldCountries\Repositories\CountryRepository;
use Oc\WorldCountries\Repositories\RegionRepository;
use Oc\WorldCountries\Support\DataPathResolver;

$countryRepository = new CountryRepository(
    dataPathResolver: new DataPathResolver('/path/to/custom/data'),
);

$regionRepository = new RegionRepository(
    countryRepository: $countryRepository,
    dataPathResolver: new DataPathResolver('/path/to/custom/data'),
);

$world = new WorldCountries($countryRepository, $regionRepository);

Package Goals

Framework agnostic — works in plain PHP, Laravel, Symfony, Laminas, and any PSR-compliant application
Offline first — all data bundled as JSON, loaded once and cached in memory
Type safe — readonly DTOs, strict types, no magic arrays
Production ready — validated datasets, meaningful exceptions, comprehensive test coverage
Wrapper friendly — clean core API designed for future Laravel and Symfony integration packages

Testing

composer test

License

MIT License. See LICENSE for details.

OctaCrafts — Scalable IT Systems & AI-Driven Digital Ecosystems

octacrafts.com · info@octacrafts.com · +1 (855) 424 4706

oc / world-countries

Maintainers

Package info

Statistics

Security