# `naisi_region_name_to_code`

从有效地区名称或 / 分隔父级路径唯一解析编码；歧义或未命中返回 false。
国内匹配 name、short_name，国际匹配 name、en_name、zh_name，籍贯匹配 name、native_place_name。
数组仅支持国内行政区划：province=数据库 level 1，city=level 2，county=level 3。
各字段可单独提供、缺失或为空；只传 county 也可匹配，唯一命中才返回编码。全部为空返回 false。
父链允许跨级，如北京(level=1)/东城(level=3)；层级与关系以数据库为准，不加直辖市特例。
籍贯输入中的 / 仅作为父级路径分隔符，不再作为完整名称的一部分匹配。不解析名称（中文）的展示组合。

## 函数签名

```php
function naisi_region_name_to_code(array|string $region, int $region_type = NAISI_REGION_TYPE_CHINA): int|false
```

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/naisi-is-ext-license-valid) 并确认返回 `true`。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：`LICENSE`；执行模式：`PROOF`。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

## 参数

### `$region`

- 类型：`array|string`
- 必填：是
- 默认值：无
- 方向：输入参数。

UTF-8 地区全称、简称、/ 路径或包含 province、city、county 的数组。

### `$region_type`

- 类型：`int`
- 必填：否
- 默认值：`NAISI_REGION_TYPE_CHINA`
- 方向：输入参数。

整数选择器：NAISI_REGION_TYPE_CHINA=1（国内行政区划）、NAISI_REGION_TYPE_GLOBAL=2（全球）、NAISI_REGION_TYPE_NATIVE_PLACE=3（籍贯）。其他整数为业务失败。

## 返回值

唯一匹配时返回整数编码；歧义、无匹配、非法输入、未授权或读取失败返回 `false`。

## 关联常量

- [`NAISI_REGION_TYPE_CHINA`](/web/developers/naisilib/const#naisi-region-type-china) = `1` — 国内行政区划。 选择地区列表、名称解析和搜索的数据集。

## 调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

```php
$region = ['province' => '江西', 'county' => '广信'];
$region_type = 1;

$result = naisi_region_name_to_code($region, $region_type);
var_export($result);
```

## 编码与异常

籍贯与国内行政区划共用编码。get/code_to_name 不增加类型参数，国内编码使用行政区划名称和父链；列表、搜索、名称解析按传入类型选择数据。get/code_to_name 可读取库中仍保留的软删除记录，其余接口过滤软删除记录；物理删除的历史记录无法查询。

参数必须与签名声明的原始 PHP 类型一致，不做弱类型转换；类型不匹配返回 `false`。参数数量错误仍遵循 PHP 标准异常规则。文本使用 UTF-8，地区文本及分隔符最多 4096 字节，不允许 NUL。没有引用输出参数。

## 版本信息

- 实现模块：`region`
- 授权类别：`LICENSE` / `PROOF`
- 失败回退：`false`
- 文档同步：`2026-10-18`