NaisiNaisi Lib Docs

naisi_region_name_to_code

查看 Markdown

从有效地区名称或 / 分隔父级路径唯一解析编码；歧义或未命中返回 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)；层级与关系以数据库为准，不加直辖市特例。 籍贯输入中的 / 仅作为父级路径分隔符，不再作为完整名称的一部分匹配。不解析名称（中文）的展示组合。

函数签名

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

调用前提

应用入口先调用 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。

关联常量

调用示例

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

$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