README

This library helps you manage regional data for mainland China, updated annually based on information from the Ministry of Civil Affairs of the People's Republic of China. The latest update was applied on April 25, 2025.

Installment

The library requires a minimum of PHP 8.4 and can be installed through Composer:

composer require lizhineng/region-china

Usage

The library includes built-in data sourced directly from the authority, so you don't need to maintain it yourself. You can find the update script in the scripts folder. First things first, let's initialize an instance of this helpful library.

use Zhineng\RegionChina\RegionManager;

$regions = RegionManager::createFromBuiltIn();

Resolve the region name from the code

Region codes are good for database persistence, but not very helpful for humans. If you have the region code, you can easily convert it back to the Chinese name.

$regions->getName($beijing = 110000); // 北京市

Retrieve provinces

When creating an interactive multi-level selector for choosing provinces, cities, and districts, it's helpful to first list all provinces in China, allowing you to display the corresponding cities and districts based on the user's selection.

$regions->getTopLevelNodes(); // [110000, 120000, 130000, ...]

Retrieve cities or districts

For example, if you want to list all cities in Guangdong Province or all districts in Guangzhou City, you only need a single API call to retrieve all sub-region codes for the specified area. You can then use these codes to obtain the corresponding names.

// Retrieve city codes for the Guangdong province
$regions->getNodes($guangdong = 440000);

// Retrieve district codes for the Guangzhou city
$regions->getNodes($guangzhou = 440100);

License

The library is released under the MIT License.