glitter1105/address-parser

一个强大的 PHP 中国地址解析器，能够智能解析混合文本中的用户信息和地址信息。支持从复杂的地址字符串中精确提取省市区、街道地址、用户姓名、手机号码、身份证号、邮政编码等信息。

1.0.0 2025-07-15 05:15 UTC

Requires

• php: >=7.4
• ext-json: *
• ext-mbstring: *

Requires (Dev)

• phpunit/phpunit: ^9.0||^10.0||^11.0
• squizlabs/php_codesniffer: ^3.0

MIT

• glitter1105

• php
• address
• parser
• Chinese
• China
• 解析器
• 省市区
• 地址解析
• 用户信息提取
• 智能识别

README

一个强大的 PHP 中国地址解析器，能够智能解析混合文本中的用户信息和地址信息。支持从复杂的地址字符串中精确提取省市区、街道地址、用户姓名、手机号码、身份证号、邮政编码等信息。

✨ 主要特性

🎯 智能地址解析

• 精确的省市区识别: 支持全国34个省级行政区、333个地级行政区、2851个县级行政区
• 多种地址格式: 兼容各种中文地址表述习惯和格式变体
• 智能关键词匹配: 基于"省"、"市"、"区"、"县"、"旗"等关键词的位置感知算法
• 同名地名处理: 有效解决重名地区的歧义性问题

👤 用户信息提取

• 姓名识别: 智能提取用户真实姓名
• 手机号码: 支持11位手机号和各种座机格式
• 身份证号: 支持18位和15位身份证号码
• 邮政编码: 精确识别6位邮政编码

🛡️ 可靠性保障

• 异常处理: 完善的错误处理机制，确保程序稳定性
• 数据验证: 多层次的输入验证和数据校验
• 容错能力: 对不完整或格式异常的地址具有较强的容错性
• 性能优化: 高效的算法设计，支持大批量地址解析

📦 安装方式

使用 Composer 安装（推荐）

composer require glitter1105/address-parser

手动安装

1. 下载源码包
2. 解压到你的项目目录
3. 引入 autoload 文件：

require_once 'vendor/autoload.php';

🚀 快速开始

基础用法

<?php
require_once 'vendor/autoload.php';

use Glitter1105\AddressParser\AddressParser;

// 解析包含用户信息的完整地址
$result = AddressParser::parse('张三 13812345678 北京市朝阳区望京街道123号');

print_r($result);
/*
输出:
Array
(
    [name] => 张三
    [mobile] => 13812345678
    [id] => 
    [postcode] => 
    [province] => 北京市
    [city] => 北京市
    [district] => 朝阳区
    [street] => 望京街道123号
)
*/

仅解析地址信息

// 如果不需要解析用户信息，可以设置第二个参数为 false
$result = AddressParser::parse('广东省深圳市南山区科技园南区', false);

print_r($result);
/*
输出:
Array
(
    [name] => 
    [mobile] => 
    [id] => 
    [postcode] => 
    [province] => 广东省
    [city] => 深圳市
    [district] => 南山区
    [street] => 科技园南区
)
*/

📋 使用示例

示例 1: 标准格式地址

$address = '李四 15987654321 上海市浦东新区陆家嘴街道东方明珠塔';
$result = AddressParser::parse($address);

echo "姓名: {$result['name']}\n";        // 李四
echo "电话: {$result['mobile']}\n";      // 15987654321
echo "省份: {$result['province']}\n";    // 上海市
echo "城市: {$result['city']}\n";        // 上海市
echo "区域: {$result['district']}\n";    // 浦东新区
echo "街道: {$result['street']}\n";      // 陆家嘴街道东方明珠塔

示例 2: 包含身份证和邮编的地址

$address = '王五 收货地址：四川省成都市武侯区 手机：[phone] 身份证：510101199001011234 邮编：610041';
$result = AddressParser::parse($address);

print_r($result);
/*
输出:
Array
(
    [name] => 王五
    [mobile] => 13612345678
    [id] => 510101199001011234
    [postcode] => 610041
    [province] => 四川省
    [city] => 成都市
    [district] => 武侯区
    [street] => 
)
*/

示例 3: 复杂格式地址

$address = '收货人：赵六，电话号码：[phone]，详细地址：江苏省南京市玄武区中山路1号，邮政编码：210000';
$result = AddressParser::parse($address);

print_r($result);

示例 4: 批量处理

$addresses = [
    '张三 13812345678 北京市朝阳区望京街道123号',
    '李四 15987654321 上海市浦东新区陆家嘴街道东方明珠塔',
    '王五 13612345678 广东省深圳市南山区科技园南区深圳湾'
];

$results = [];
foreach ($addresses as $address) {
    $results[] = AddressParser::parse($address);
}

// 输出所有解析结果
foreach ($results as $result) {
    echo "姓名: {$result['name']}, 城市: {$result['city']}, 区域: {$result['district']}\n";
}

🔧 高级用法

异常处理

use Glitter1105\AddressParser\AddressParser;
use Glitter1105\AddressParser\Exceptions\InvalidArgumentException;

try {
    $result = AddressParser::parse('');  // 空地址
} catch (InvalidArgumentException $e) {
    echo "参数错误: " . $e->getMessage();
}

try {
    $result = AddressParser::parse(null);  // 无效类型
} catch (InvalidArgumentException $e) {
    echo "参数类型错误: " . $e->getMessage();
}

自定义处理逻辑

// 检查解析结果的完整性
function validateParseResult($result) {
    $required = ['name', 'mobile', 'province', 'city'];
    
    foreach ($required as $field) {
        if (empty($result[$field])) {
            throw new Exception("缺少必需字段: {$field}");
        }
    }
    
    return true;
}

$address = '张三 13812345678 北京市朝阳区望京街道123号';
$result = AddressParser::parse($address);

if (validateParseResult($result)) {
    echo "地址解析完整！";
}

🏗️ 系统要求

• PHP 版本: 7.4 或更高版本
• PHP 扩展:
  • ext-json: JSON 数据处理
  • ext-mbstring: 多字节字符串处理（中文支持）
• 依赖包: 无外部依赖

📊 支持的地址格式

省级行政区

• 省: 如"广东省"、"山东省"
• 直辖市: 如"北京市"、"上海市"
• 自治区: 如"新疆维吾尔自治区"、"西藏自治区"
• 特别行政区: 如"香港特别行政区"、"澳门特别行政区"

地级行政区

• 地级市: 如"深圳市"、"杭州市"
• 自治州: 如"延边朝鲜族自治州"
• 盟: 如"锡林郭勒盟"

县级行政区

• 市辖区: 如"朝阳区"、"浦东新区"
• 县: 如"海淀县"、"宝安县"
• 自治县: 如"秀山土家族苗族自治县"
• 旗: 如"察哈尔右翼前旗"

🎯 算法特点

地址解析算法

1. 预处理阶段

   • 清理空格、标点符号等干扰字符
   • 标准化行政区划名称表述
   • 移除常见的非地名关键词

2. 关键词提取

   • 基于位置感知的关键词识别
   • 优先级排序：区县 > 市 > 省
   • 特殊地名格式处理

3. 智能匹配

   • 多级行政区划数据库匹配
   • 同名地名的歧义性解决
   • 不完整地址的智能补全

用户信息提取算法

1. 正则表达式匹配

   • 手机号: 支持11位手机号和各种座机格式
   • 身份证: 支持18位和15位格式
   • 邮政编码: 6位数字格式

2. 启发式姓名识别

   • 基于词长度和位置的姓名推断
   • 常见姓名模式识别
   • 与其他信息的上下文关联

🚨 注意事项

1. 数据准确性: 解析结果的准确性取决于输入地址的完整性和规范性
2. 性能考虑: 对于大批量数据处理，建议适当控制并发数量
3. 字符编码: 确保输入数据使用 UTF-8 编码
4. 特殊字符: 避免使用特殊符号和表情符号

🤝 贡献指南

我们欢迎任何形式的贡献！

报告问题

• 在 GitHub Issues 提交 bug 报告
• 提供详细的错误信息和复现步骤

提交代码

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

开发规范

• 遵循 PSR-4 自动加载规范
• 添加适当的单元测试
• 确保代码风格一致
• 添加详细的注释文档

📄 许可证

本项目采用 MIT 许可证。详情请查看 LICENSE 文件。

🙏 致谢

• 感谢所有贡献者的努力和支持
• 参考了国家标准《中华人民共和国行政区划代码》(GB/T 2260)
• 使用了开源的行政区划数据

📞 联系方式

• 作者: glitter1105
• 邮箱: [e-mail]
• GitHub: https://github.com/glitter1105/address-parser

🔗 相关链接

• Packagist
• GitHub Releases
• 文档中心

⭐ 如果这个项目对你有帮助，请给我们一个 Star！