PHPackages oc/world-countries - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. oc/world-countries ActiveLibrary[Utility & Helpers](/categories/utility) oc/world-countries ================== Framework-agnostic access to world countries and ISO 3166-2 regions from bundled JSON datasets v1.0.0(1mo ago)041MITPHPPHP ^8.2 Since Jun 12Pushed 1mo agoCompare [ Source](https://github.com/octacrafts/oc-world-countries)[ Packagist](https://packagist.org/packages/oc/world-countries)[ Docs](https://octacrafts.com)[ RSS](/packages/oc-world-countries/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (1)Versions (2)Used By (1) oc/world-countries ================== [](#ocworld-countries) [![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE) Framework-agnostic access to world countries and ISO 3166-2 regions/subdivisions from bundled JSON datasets. Maintained by **[OctaCrafts](https://octacrafts.com)**. No database. No external API. No runtime downloads. Everything works entirely from local JSON files shipped with the package. About OctaCrafts ---------------- [](#about-octacrafts) [OctaCrafts](https://octacrafts.com) 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](https://github.com/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](https://github.com/octacrafts/oc-world-countries-laravel). Symfony and other framework wrappers are planned. Requirements ------------ [](#requirements) - PHP 8.2+ - `ext-json` - `ext-mbstring` Installation ------------ [](#installation) ``` composer require oc/world-countries ``` Quick Start ----------- [](#quick-start) ``` use Oc\WorldCountries\WorldCountries; $world = new WorldCountries(); $pakistan = $world->country('PK'); $regions = $world->regions('PK'); $punjab = $world->region('PK', 'PB'); ``` Usage Examples -------------- [](#usage-examples) ### Countries [](#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 [](#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 ------------- [](#api-reference) ### `WorldCountries` [](#worldcountries) MethodReturn TypeDescription`countries()``list`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`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`Search countries by name or code`searchRegions(string $countryCode, string $query)``list`Search regions by name or code`countryOptions()``array`Alpha-2 code to country name map`regionOptions(string $countryCode)``array`Region code to region name map### DTOs [](#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 -------------- [](#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 ------------- [](#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 ------- [](#testing) ``` composer test ``` License ------- [](#license) MIT License. See [LICENSE](LICENSE) for details. --- **[OctaCrafts](https://octacrafts.com)** — Scalable IT Systems & AI-Driven Digital Ecosystems [octacrafts.com](https://octacrafts.com) · · +1 (855) 424 4706 ### Health Score 39 — LowBetter than 84% of packages Maintenance90 Actively maintained with recent releases Popularity4 Limited adoption so far Community8 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 46d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/278240197?v=4)[octacrafts](/maintainers/octacrafts)[@octacrafts](https://github.com/octacrafts) --- Top Contributors [![WasifBoostzone](https://avatars.githubusercontent.com/u/275062263?v=4)](https://github.com/WasifBoostzone "WasifBoostzone (1 commits)") --- Tags phpcountriesISO 3166geographyiso\_3166\_2regionsworld countries ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/oc-world-countries/health.svg) ``` [![Health](https://phpackages.com/badges/oc-world-countries/health.svg)](https://phpackages.com/packages/oc-world-countries) ``` ### Alternatives [league/iso3166 ISO 3166-1 PHP Library 69938.4M142](/packages/league-iso3166)[webpatser/laravel-countries Modern Laravel Countries package providing ISO 3166-2, ISO 3166-3, currency, capital and more for all countries. Compatible with Laravel 11.x, 12.x, and 13.x. 8452.9M10](/packages/webpatser-laravel-countries)[plin-code/laravel-istat-geography Laravel package for importing and managing Italian geography data from ISTAT 107.0k](/packages/plin-code-laravel-istat-geography) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)