Skip to content

Commit 2dba751

Browse files
author
苏青安
committed
README调整
1 parent 309b111 commit 2dba751

File tree

3 files changed

+199
-50
lines changed

3 files changed

+199
-50
lines changed

‎README.md

+62-49
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,43 @@
11
# hejunjie/address-parser
22

3-
一个简单实用的 PHP 地址解析工具，可以从混杂的字符串中提取出 **姓名、手机号、身份证、邮编、以及完整的省市区地址信息**。
3+
<div align="center">
4+
<a href="./README.md">English</a>｜<a href="./README.zh-CN.md">简体中文</a>
5+
<hr width="50%"/>
6+
</div>
47

5-
> 🚀 适用于快递地址、用户信息录入等场景，自动识别结构化信息。
8+
An intelligent address parser that extracts name, phone number, ID number, region, and detailed address from unstructured text—perfect for e-commerce, logistics, and CRM systems.
69

7-
如果你不想要部署，只是想要进行使用，可以 👉 [点击此处进行使用](https://tools.hejunjie.life/#/external/address-parser)
10+
---
11+
12+
A simple and practical PHP address parsing tool that can extract **name, phone number, ID card number, postal code, and full province-city-district address** from unstructured strings.
13+
14+
> 🚀 Ideal for use cases like shipping addresses and user information entry, automatically identifying and structuring key data.
815
9-
支持批量查询
16+
If you don’t want to deploy it yourself and just want to use it directly, you can 👉 [Click here to use it](https://tools.hejunjie.life/#/external/address-parser)
17+
18+
Batch queries are supported.
1019

1120
---
1221

13-
## ✨ 特性
22+
## ✨ Features
1423

15-
- 自动识别：支持姓名、手机号、身份证、邮编提取
16-
- 地址解析：基于省市区行政区划数据，智能匹配行政区域
17-
- 结构化返回：统一结构输出，便于前后端对接
18-
- 零依赖：纯 PHP 编写，无需额外扩展
19-
- 支持 PHP 8+
24+
- Auto Recognition: Supports extraction of name, phone number, ID card, and postal code
25+
- Address Parsing: Intelligently matches administrative regions based on province/city/district data
26+
- Structured Output: Returns data in a unified structure, easy for frontend-backend integration
27+
- Zero Dependencies: Written in pure PHP, no additional extensions required
28+
- PHP 8+ Supported
2029

2130
---
2231

23-
## 📦 安装
32+
## 📦 Installation
2433

25-
使用 Composer 安装：
34+
Install via Composer:
2635

2736
```bash
2837
composer require hejunjie/address-parser
2938
```
3039

31-
## 🧠 使用示例
40+
## 🧠 Usage Example
3241

3342
```php
3443
use Hejunjie\AddressParser\AddressParser;
@@ -41,7 +50,7 @@ print_r($parsed);
4150

4251
```
4352

44-
输出结果
53+
Output Result
4554

4655
```php
4756
[
@@ -56,69 +65,73 @@ print_r($parsed);
5665
]
5766
```
5867

59-
## 🧩 返回字段说明
68+
## 🧩 Response Field Description
6069

61-
| 字段名 | 说明 |
70+
| Parameter | Description |
6271
|:-------|:-----|
63-
| name | 姓名 |
64-
| mobile | 手机号 |
65-
| idn | 身份证号 |
66-
| postcode | 邮政编码 |
67-
| province | 省份名称 |
68-
| city | 城市名称 |
69-
| region | 区/县名称 |
70-
| street | 详细地址（去除省市区后的部分） |
72+
| name | User's full name |
73+
| mobile | User's mobile number |
74+
| idn | User's national ID card number |
75+
| postcode | Zip/postal code |
76+
| province | Name of the province |
77+
| city | Name of the city |
78+
| region | Name of the district or county |
79+
| street | Remaining address after removing province, city, and district |
7180

72-
## 🧰 用途 & 背景
81+
## 🧰 Purpose & Background
7382

74-
在实际业务中，用户填写的地址往往是非结构化的，例如：
83+
In real-world scenarios, user-submitted addresses are often unstructured. For example:
7584

7685
> 张三 13512345678 北京市朝阳区建国路88号 邮编100000
7786
78-
将这些信息手动拆分不仅低效，而且容易出错。`hejunjie/address-parser` 就是为了解决这种 **非结构化地址的自动解析** 而设计的，广泛适用于：
87+
Manually parsing such data is not only inefficient but also error-prone. The `hejunjie/address-parser` is designed specifically to solve this problem of **unstructured address parsing**, and is suitable for a wide range of use cases:
88+
89+
- 🛒 Processing order addresses in e-commerce systems
90+
- 📦 Address recognition in logistics and delivery services
91+
- 🧾 User profile completion in admin panels
92+
- 📱 Address input validation in mini-programs or mobile apps
7993

80-
- 🛒 电商系统中的订单地址处理
81-
- 📦 快递物流系统地址识别
82-
- 🧾 后台管理系统用户信息补全
83-
- 📱 小程序/APP 用户地址录入校验
94+
Whether for personal projects or enterprise systems, it significantly boosts automation and accuracy in address handling.
8495

85-
无论是个人项目还是企业系统，它都能快速提升地址处理的自动化与准确率。
96+
If you have any questions or suggestions, feel free to submit an issue or PR — I’ll do my best to respond.
8697

87-
有啥问题或者建议都欢迎提 issue 或 PR，我会尽量回复。
98+
## 🙏 Acknowledgements
8899

89-
## 🙏 致谢
90-
这个包最初的灵感，来自一位朋友在我另一个仓库的 issues 里提到的想法，还贴心地分享了其他朋友的实现：[pupuk/address](https://github.com/pupuk/address)。当时就觉得这个方向挺有意思，也正是因为他的启发，我才动手做了 `hejunjie/address-parser`。
100+
The inspiration for this package originally came from a friend who mentioned the idea in an issue on one of my other repositories, even kindly sharing another friend's implementation: [pupuk/address](https://github.com/pupuk/address). I found the concept very interesting, and thanks to that inspiration, I created `hejunjie/address-parser`.
91101

92-
感谢他的思路分享，也希望这个小工具能帮到更多人 🙌
102+
Thanks to him for the idea — I hope this little tool helps more people 🙌
93103

94-
## 🔧 更多工具包（可独立使用，也可统一安装）
104+
## 🔧 Additional Toolkits (Can be used independently or installed together)
95105

96-
本项目最初是从 [hejunjie/tools](https://github.com/zxc7563598/php-tools) 拆分而来，如果你想一次性安装所有功能组件，也可以使用统一包：
106+
This project was originally extracted from [hejunjie/tools](https://github.com/zxc7563598/php-tools).
107+
To install all features in one go, feel free to use the all-in-one package:
97108

98109
```bash
99110
composer require hejunjie/tools
100111
```
101112

102-
当然你也可以按需选择安装以下功能模块：
113+
Alternatively, feel free to install only the modules you need：
114+
115+
[hejunjie/utils](https://github.com/zxc7563598/php-utils) - A lightweight and practical PHP utility library that offers a collection of commonly used helper functions for files, strings, arrays, and HTTP requests—designed to streamline development and support everyday PHP projects.
103116

104-
[hejunjie/cache](https://github.com/zxc7563598/php-cache) - 多层缓存系统，基于装饰器模式。
117+
[hejunjie/cache](https://github.com/zxc7563598/php-cache) - A layered caching system built with the decorator pattern. Supports combining memory, file, local, and remote caches to improve hit rates and simplify cache logic.
105118

106-
[hejunjie/china-division](https://github.com/zxc7563598/php-china-division) - 中国省市区划分数据包。
119+
[hejunjie/china-division](https://github.com/zxc7563598/php-china-division) - Regularly updated dataset of China's administrative divisions with ID-card address parsing. Distributed via Composer and versioned for use in forms, validation, and address-related features
107120

108-
[hejunjie/error-log](https://github.com/zxc7563598/php-error-log) - 责任链日志上报系统。
121+
[hejunjie/error-log](https://github.com/zxc7563598/php-error-log) - An error logging component using the Chain of Responsibility pattern. Supports multiple output channels like local files, remote APIs, and console logs—ideal for flexible and scalable logging strategies.
109122

110-
[hejunjie/mobile-locator](https://github.com/zxc7563598/php-mobile-locator) - 国内手机号归属地 & 运营商识别。
123+
[hejunjie/mobile-locator](https://github.com/zxc7563598/php-mobile-locator) - A mobile number lookup library based on Chinese carrier rules. Identifies carriers and regions, suitable for registration checks, user profiling, and data archiving.
111124

112-
[hejunjie/utils](https://github.com/zxc7563598/php-utils) - 常用工具方法集合。
125+
[hejunjie/address-parser](https://github.com/zxc7563598/php-address-parser) - An intelligent address parser that extracts name, phone number, ID number, region, and detailed address from unstructured text—perfect for e-commerce, logistics, and CRM systems.
113126

114-
[hejunjie/url-signer](https://github.com/zxc7563598/php-url-signer) - URL 签名工具，支持对 URL 进行签名和验证。
127+
[hejunjie/url-signer](https://github.com/zxc7563598/php-url-signer) - A PHP library for generating URLs with encryption and signature protection—useful for secure resource access and tamper-proof links.
115128

116-
[hejunjie/google-authenticator](https://github.com/zxc7563598/php-google-authenticator) - Google Authenticator 及类似应用的密钥生成、二维码创建和 OTP 验证。
129+
[hejunjie/google-authenticator](https://github.com/zxc7563598/php-google-authenticator) - A PHP library for generating and verifying Time-Based One-Time Passwords (TOTP). Compatible with Google Authenticator and similar apps, with features like secret generation, QR code creation, and OTP verification.
117130

118-
[hejunjie/simple-rule-engine](https://github.com/zxc7563598/php-simple-rule-engine) - 一个轻量、易用的 PHP 规则引擎，支持多条件组合、动态规则执行。
131+
[hejunjie/simple-rule-engine](https://github.com/zxc7563598/php-simple-rule-engine) - A lightweight and flexible PHP rule engine supporting complex conditions and dynamic rule execution—ideal for business logic evaluation and data validation.
119132

120-
👀 所有包都遵循「轻量实用、解放双手」的原则，能单独用，也能组合用，自由度高，欢迎 star 🌟 或提 issue。
133+
👀 All packages follow the principles of being lightweight and practical — designed to save you time and effort. They can be used individually or combined flexibly. Feel free to ⭐ star the project or open an issue anytime!
121134

122135
---
123136

124-
该库后续将持续更新，添加更多实用功能。欢迎大家提供建议和反馈，我会根据大家的意见实现新的功能，共同提升开发效率。
137+
This library will continue to be updated with more practical features. Suggestions and feedback are always welcome — I’ll prioritize new functionality based on community input to help improve development efficiency together.

‎README.zh-CN.md

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# hejunjie/address-parser
2+
3+
<div align="center">
4+
<a href="./README.md">English</a>｜<a href="./README.zh-CN.md">简体中文</a>
5+
<hr width="50%"/>
6+
</div>
7+
8+
收货地址智能解析工具，支持从非结构化文本中提取姓名、手机号、身份证号、省市区、详细地址等字段，适用于电商、物流、CRM 等系统。
9+
10+
---
11+
12+
一个简单实用的 PHP 地址解析工具，可以从混杂的字符串中提取出 **姓名、手机号、身份证、邮编、以及完整的省市区地址信息**。
13+
14+
> 🚀 适用于快递地址、用户信息录入等场景，自动识别结构化信息。
15+
16+
如果你不想要部署，只是想要进行使用，可以 👉 [点击此处进行使用](https://tools.hejunjie.life/#/external/address-parser)
17+
18+
支持批量查询
19+
20+
---
21+
22+
## ✨ 特性
23+
24+
- 自动识别：支持姓名、手机号、身份证、邮编提取
25+
- 地址解析：基于省市区行政区划数据，智能匹配行政区域
26+
- 结构化返回：统一结构输出，便于前后端对接
27+
- 零依赖：纯 PHP 编写，无需额外扩展
28+
- 支持 PHP 8+
29+
30+
---
31+
32+
## 📦 安装
33+
34+
使用 Composer 安装：
35+
36+
```bash
37+
composer require hejunjie/address-parser
38+
```
39+
40+
## 🧠 使用示例
41+
42+
```php
43+
use Hejunjie\AddressParser\AddressParser;
44+
45+
$raw = '张三，13512345678,410123199001011234 重庆攀枝花市东区机场路88号 邮编100000';
46+
47+
$parsed = AddressParser::parse($raw);
48+
49+
print_r($parsed);
50+
51+
```
52+
53+
输出结果
54+
55+
```php
56+
[
57+
'name' => '张三',
58+
'mobile' => '13512345678',
59+
'idn' => '410123199001011234',
60+
'postcode' => '100000',
61+
'province' => '四川省',
62+
'city' => '攀枝花市',
63+
'region' => '东区',
64+
'street' => '机场路88号'
65+
]
66+
```
67+
68+
## 🧩 返回字段说明
69+
70+
| 字段名 | 说明 |
71+
| :------- | :----------------------------- |
72+
| name | 姓名 |
73+
| mobile | 手机号 |
74+
| idn | 身份证号 |
75+
| postcode | 邮政编码 |
76+
| province | 省份名称 |
77+
| city | 城市名称 |
78+
| region | 区/县名称 |
79+
| street | 详细地址（去除省市区后的部分） |
80+
81+
## 🧰 用途 & 背景
82+
83+
在实际业务中，用户填写的地址往往是非结构化的，例如：
84+
85+
> 张三 13512345678 北京市朝阳区建国路 88 号 邮编 100000
86+
87+
将这些信息手动拆分不仅低效，而且容易出错。`hejunjie/address-parser` 就是为了解决这种 **非结构化地址的自动解析** 而设计的，广泛适用于：
88+
89+
- 🛒 电商系统中的订单地址处理
90+
- 📦 快递物流系统地址识别
91+
- 🧾 后台管理系统用户信息补全
92+
- 📱 小程序/APP 用户地址录入校验
93+
94+
无论是个人项目还是企业系统，它都能快速提升地址处理的自动化与准确率。
95+
96+
有啥问题或者建议都欢迎提 issue 或 PR，我会尽量回复。
97+
98+
## 🙏 致谢
99+
100+
这个包最初的灵感，来自一位朋友在我另一个仓库的 issues 里提到的想法，还贴心地分享了其他朋友的实现：[pupuk/address](https://github.com/pupuk/address)。当时就觉得这个方向挺有意思，也正是因为他的启发，我才动手做了 `hejunjie/address-parser`。
101+
102+
感谢他的思路分享，也希望这个小工具能帮到更多人 🙌
103+
104+
## 🔧 更多工具包（可独立使用，也可统一安装）
105+
106+
本项目最初是从 [hejunjie/tools](https://github.com/zxc7563598/php-tools) 拆分而来，如果你想一次性安装所有功能组件，也可以使用统一包：
107+
108+
```bash
109+
composer require hejunjie/tools
110+
```
111+
112+
当然你也可以按需选择安装以下功能模块：
113+
114+
[hejunjie/utils](https://github.com/zxc7563598/php-utils) - 一个零碎但实用的 PHP 工具函数集合库。包含文件、字符串、数组、网络请求等常用函数的工具类集合，提升开发效率，适用于日常 PHP 项目辅助功能。
115+
116+
[hejunjie/cache](https://github.com/zxc7563598/php-cache) - 基于装饰器模式实现的多层缓存系统，支持内存、文件、本地与远程缓存组合，提升缓存命中率，简化缓存管理逻辑。
117+
118+
[hejunjie/china-division](https://github.com/zxc7563598/php-china-division) - 定期更新，全国最新省市区划分数据，身份证号码解析地址，支持 Composer 安装与版本控制，适用于表单选项、数据校验、地址解析等场景。
119+
120+
[hejunjie/error-log](https://github.com/zxc7563598/php-error-log) - 基于责任链模式的错误日志处理组件，支持多通道日志处理（如本地文件、远程 API、控制台输出），适用于复杂日志策略场景。
121+
122+
[hejunjie/mobile-locator](https://github.com/zxc7563598/php-mobile-locator) - 基于国内号段规则的手机号码归属地查询库，支持运营商识别与地区定位，适用于注册验证、用户画像、数据归档等场景。
123+
124+
[hejunjie/address-parser](https://github.com/zxc7563598/php-address-parser) - 收货地址智能解析工具，支持从非结构化文本中提取姓名、手机号、身份证号、省市区、详细地址等字段，适用于电商、物流、CRM 等系统。
125+
126+
[hejunjie/url-signer](https://github.com/zxc7563598/php-url-signer) - 用于生成带签名和加密保护的 URL 链接的 PHP 工具包，适用于需要保护资源访问的场景
127+
128+
[hejunjie/google-authenticator](https://github.com/zxc7563598/php-google-authenticator) - 一个用于生成和验证时间基础一次性密码（TOTP）的 PHP 包，支持 Google Authenticator 及类似应用。功能包括密钥生成、二维码创建和 OTP 验证。
129+
130+
[hejunjie/simple-rule-engine](https://github.com/zxc7563598/php-simple-rule-engine) - 一个轻量、易用的 PHP 规则引擎，支持多条件组合、动态规则执行，适合业务规则判断、数据校验等场景。
131+
132+
👀 所有包都遵循「轻量实用、解放双手」的原则，能单独用，也能组合用，自由度高，欢迎 star 🌟 或提 issue。
133+
134+
---
135+
136+
该库后续将持续更新，添加更多实用功能。欢迎大家提供建议和反馈，我会根据大家的意见实现新的功能，共同提升开发效率。

‎composer.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "hejunjie/address-parser",
3-
"description": "收货地址智能解析工具，支持从非结构化文本中提取姓名、手机号、身份证号、省市区、详细地址等字段，适用于电商、物流、CRM 等系统。",
3+
"description": "An intelligent address parser that extracts name, phone number, ID number, region, and detailed address from unstructured text—perfect for e-commerce, logistics, and CRM systems.",
44
"type": "library",
55
"license": "MIT",
66
"autoload": {

0 commit comments

Comments
 (0)