告别手动维护国家地区列表的烦恼：使用dougsisk/laravel-country-state轻松搞定Laravel表单！-composer-PHP中文网

告别手动维护国家地区列表的烦恼：使用dougsisk/laravel-country-state轻松搞定Laravel表单！

WBOY

发布： 2025-07-15 14:28:08

原创

800人浏览过

每一个开发者都可能遇到过这样的场景：在构建一个电商网站、用户注册系统或是任何需要地理位置信息的应用时，你都需要提供一个让用户选择国家和地区的下拉菜单。起初，你可能会想，这不就是几个数组嘛，手动写进去就好了。但随着业务的扩展，你需要支持更多国家，甚至要精确到州、省、市，手动维护这些列表简直是一场噩梦：

数据量庞大且易错： 全球有近200个国家，每个国家又有几十个甚至上百个州/省，手动录入这些数据不仅耗时耗力，还极易引入拼写错误或遗漏。
更新维护困难： 国家名称、行政区划有时会发生变化，手动更新意味着你需要不断地关注这些信息，并修改代码。
国际化与标准化： 如何确保国家和地区名称的英文拼写准确无误？如何统一使用 ISO 编码作为后台标识？这些都是手动维护难以解决的挑战。
代码冗余与耦合： 如果在多个地方都需要这些数据，你可能会复制粘贴相同的数组，导致代码冗余，难以管理。

composer在线学习地址：学习地址

幸好，Laravel 强大的生态系统总能为我们提供优雅的解决方案。今天，我就要向大家介绍一个能彻底解决这个痛点的 Composer 包——dougsisk/laravel-country-state。

引入 `dougsisk/laravel-country-state`：告别手动维护的时代

dougsisk/laravel-country-state 是一个专为 Laravel 11.0+ 设计的实用工具，它提供了一个简洁的 API 来获取国家和地区（州/省）的英文名称列表，并支持 ISO 编码。得益于 Composer 强大的包管理能力，安装这个库简直是小菜一碟：

首先，通过 Composer 将其添加到你的 Laravel 项目中：

<code class="bash">composer require dougsisk/laravel-country-state</code>

登录后复制

安装完成后，如果你使用的是 Laravel 11.0+ 并且开启了包自动发现功能，那么你无需进行任何额外配置。否则，你可能需要在 config/app.php 文件的 providers 数组中手动添加服务提供者：

<code class="php">// config/app.php

'providers' => [
    // ...
    DougSisk\CountryState\CountryStateServiceProvider::class,
],</code>

登录后复制

为了更好地控制和定制国家地区数据，你可以发布其配置文件到你的项目中：

<code class="bash">php artisan vendor:publish --provider="DougSisk\CountryState\CountryStateServiceProvider" --tag="config"</code>

登录后复制

这会在 config 目录下生成一个 country-state.php 文件，你可以在其中进行一些配置，例如：

<code class="php">// config/country-state.php

return [
    // 预加载指定国家的州/省数据，提高性能
    'preloadCountryStates' => ['CA', 'MX', 'US'],

    // 限制只返回指定国家的列表
    'limitCountries' => ['CA', 'MX', 'US']
];</code>

登录后复制

通过 preloadCountryStates，你可以预先加载常用国家的州/省数据，避免每次请求时都去加载所有数据。而 limitCountries 则允许你根据业务需求，只显示部分国家，这对于只服务特定区域的应用来说非常实用。

轻松使用：获取国家与地区列表

dougsisk/laravel-country-state 提供了一个方便的 Facade 接口 CountryState，让你可以轻松访问国家和地区数据。别忘了在你的文件中导入这个 Facade：

ClipDrop

Stability.AI出品的图片处理系列工具（背景移除、图片放大、打光）

112

查看详情

<code class="php">use CountryState;</code>

登录后复制

获取所有国家列表：

<code class="php">$countries = CountryState::getCountries();

/*
$countries 的示例输出（部分）：
[
    "AD" => "Andorra",
    "AE" => "United Arab Emirates",
    "AF" => "Afghanistan",
    // ...
    "US" => "United States",
    // ...
]
*/</code>

登录后复制

getCountries() 方法返回一个关联数组，键是国家的两字母 ISO 编码，值是国家的英文名称。这对于构建 <select></select> 标签的 value 和 text 都非常方便。

获取指定国家的州/省列表：

如果你需要获取某个国家的所有州或省份列表，只需传入该国家的两字母 ISO 编码即可：

<code class="php">$states = CountryState::getStates('US'); // 获取美国的所有州

/*
$states 的示例输出（部分）：
[
    "AL" => "Alabama",
    "AK" => "Alaska",
    "AZ" => "Arizona",
    // ...
    "WY" => "Wyoming"
]
*/</code>

登录后复制

同样，返回的也是一个关联数组，键是州/省的两字母 ISO 编码，值是其英文名称。这使得在表单中实现国家-地区级联选择变得异常简单。