PHPackages                             universal-packages/country-service - 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. universal-packages/country-service

ActiveLibrary[Utility & Helpers](/categories/utility)

universal-packages/country-service
==================================

PHP 8.1+ 国家/省份查询库，数据源自 Shopify Country Service

v2.0.0(5mo ago)0269MITPHPPHP >=8.1CI passing

Since Mar 6Pushed 5mo agoCompare

[ Source](https://github.com/UniversalPackages/CountryService)[ Packagist](https://packagist.org/packages/universal-packages/country-service)[ RSS](/packages/universal-packages-country-service/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (8)Dependencies (1)Versions (10)Used By (0)

Country Service
===============

[](#country-service)

PHP 8.1+ 国家/省份查询库，数据源自 [Shopify Country Service](https://country-service.shopifycloud.com)。

安装
--

[](#安装)

通过 [Packagist](https://packagist.org/packages/universal-packages/country-service) 安装：

```
composer require universal-packages/country-service
```

用法
--

[](#用法)

```
use UniversalPackages\CountryService\CountryService;
use UniversalPackages\CountryService\DataLocale;

$service = new CountryService(DataLocale::EN_US);

// 国家列表
$countries = $service->getCountries();

// 某国省份
$provinces = $service->getProvinces('CN');

// 按国家名查询（大小写不敏感，自动 trim）
$country = $service->getCountryByName('China');      // Country(code: CN, name: China, ...)
$country = $service->getCountryByName('  china  ');  // 同样可命中
$country = $service->getCountryByName('NoCountry');  // null

// 解析：国家代码 → 国家名 + 省份列表
$result = $service->resolve('CN');  // China, 31 provinces

// 解析：国家-省份代码 → 国家名 + 省份名
$result = $service->resolve('CN-GD');  // China / Guangdong (GD)

// 省份不存在时的降级处理
$result = $service->resolve('CN-XX');                            // null（默认行为）
$result = $service->resolve('CN-XX', allowInvalidProvince: true); // CountryProvinceResolveResult(country: China, countryCode: CN, province: XX, provinceCode: XX)
```

API 概览
------

[](#api-概览)

方法说明`getCountries(): Country[]`返回当前 locale 的全部国家`getProvinces(string $countryCode): Province[]`根据国家代码获取省份（大小写不敏感）`getCountryByName(string $countryName): ?Country`根据国家名精确匹配国家对象（大小写不敏感，自动 trim）`resolve(string $input, bool $allowInvalidProvince = false): CountryResolveResult|CountryProvinceResolveResult|null`解析国家代码或国家-省份代码（支持 `UY-UY-AR` 这类省份代码含连字符）。`allowInvalidProvince` 为 true 时，省份不存在会返回 `CountryProvinceResolveResult`（省份字段使用原始输入）性能说明
----

[](#性能说明)

- 国家主数据按国家代码建立内存索引（`countryCode => Country`）。
- 国家名查询使用惰性名称索引（`normalizedName => countryCode`），首次调用时构建。
- 名称索引仅保存国家代码，查询时回查主索引，在保持查询速度的同时节省内存占用。

命令
--

[](#命令)

命令说明`composer fetch-countries`拉取国家/省份数据`composer test`运行测试数据更新
----

[](#数据更新)

GitHub Actions 每周一自动执行 `fetch-countries`，并提交变更。

许可证
---

[](#许可证)

[MIT License](LICENSE)

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance73

Regular maintenance activity

Popularity15

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 80% 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

Every ~1 days

Total

8

Last Release

150d ago

Major Versions

v1.3.1 → v2.0.02026-03-11

### Community

Maintainers

![](https://www.gravatar.com/avatar/3d7872292c2e55eb538a04bd5b54d7f3282d570441f6bd1df17ce9775de161e6?d=identicon)[PrintNow](/maintainers/PrintNow)

![](https://avatars.githubusercontent.com/u/20787403?v=4)[mark](/maintainers/markbeam)[@markbeam](https://github.com/markbeam)

---

Top Contributors

[![PrintNow](https://avatars.githubusercontent.com/u/28396104?v=4)](https://github.com/PrintNow "PrintNow (12 commits)")[![markbeam](https://avatars.githubusercontent.com/u/20787403?v=4)](https://github.com/markbeam "markbeam (3 commits)")

---

Tags

country-datacountry-service

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/universal-packages-country-service/health.svg)

```
[![Health](https://phpackages.com/badges/universal-packages-country-service/health.svg)](https://phpackages.com/packages/universal-packages-country-service)
```

###  Alternatives

[ipinfo/ipinfo

The official PHP library for IPinfo, the most reliable, accurate, and in-depth source of IP address data available anywhere. We process terabytes of data to produce our custom IP geolocation, company, carrier and IP type data sets. Visit our developer docs at https://ipinfo.io/developers.

2891.4M22](/packages/ipinfo-ipinfo)[alibabacloud/dysmsapi-20170525

Alibaba Cloud Dysmsapi (20170525) SDK Library for PHP

18463.8k43](/packages/alibabacloud-dysmsapi-20170525)[rlofls/drag-captcha

Drag-and-drop graphics verification, small and easy to use

501.9k](/packages/rlofls-drag-captcha)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)