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

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