PHPackages                             hejunjie/address-parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. hejunjie/address-parser

ActiveLibrary[Parsing & Serialization](/categories/parsing)

hejunjie/address-parser
=======================

收货地址智能解析工具，支持从非结构化文本中提取姓名、手机号、身份证号、省市区、详细地址等字段，适用于电商、物流、CRM 等系统 | 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.

v2.0.0(1mo ago)101.8k↓91.1%51MITPHPPHP ^7.4 || ^8.0CI failing

Since Apr 15Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/zxc7563598/php-address-parser)[ Packagist](https://packagist.org/packages/hejunjie/address-parser)[ RSS](/packages/hejunjie-address-parser/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (5)Dependencies (2)Versions (6)Used By (1)

hejunjie/address-parser
=======================

[](#hejunjieaddress-parser)

 [English](./README.md)｜[简体中文](./README.zh-CN.md)

An intelligent address parser that extracts name, phone number, ID number, province, city, district, and detailed address from unstructured text — ideal for e-commerce, logistics, and CRM systems.

> For a quick project overview, check out the [Zread analysis](https://zread.ai/zxc7563598/php-address-parser). If you'd rather not deploy it yourself, try the [online tool](https://hejunjie.life/composer/address-parser), which also supports batch queries.

Features
--------

[](#features)

- **User Info Extraction**: Automatically recognizes name, phone number, ID number, and postal code
- **Smart Address Matching**: Intelligently resolves administrative divisions using nationwide province/city/district data
- **Structured Output**: Returns a consistent array format for easy frontend-backend integration
- **Flexible Configuration**: Supports custom division data sources and configurable fallback values
- **PHP 7.4+ / 8.0+** with ext-mbstring required

Installation
------------

[](#installation)

```
composer require hejunjie/address-parser
```

Quick Start
-----------

[](#quick-start)

```
use Hejunjie\AddressParser\AddressParser;

$raw = '张三，13512345678，410123199001011234 重庆攀枝花市东区机场路88号 邮编100000';

$parsed = AddressParser::parse($raw);

print_r($parsed);
```

Output:

```
[
    'name'     => '张三',
    'mobile'   => '13512345678',
    'idn'      => '410123199001011234',
    'postcode' => '100000',
    'province' => '四川省',
    'city'     => '攀枝花市',
    'region'   => '东区',
    'street'   => '机场路88号',
]
```

API
---

[](#api)

### `AddressParser::parse()`

[](#addressparserparse)

```
public static function parse(
    string $string,         // Raw address string to parse
    bool $user = true,      // Whether to extract user info (name, phone, ID, postcode)
    string $unknownValue = '未知',  // Fallback value when a region cannot be matched
    array $level1Data = [], // Custom province-level data; uses built-in data if empty
    array $level2Data = [], // Custom city-level data
    array $level3Data = []  // Custom district/county-level data
): array
```

> Built-in division data is sourced from [hejunjie/china-division](https://github.com/zxc7563598/php-china-division) and updated regularly.

**Parameters:**

ParameterTypeDefaultDescription`$string``string`requiredThe raw address string to parse`$user``bool``true`Set to `false` to skip user info extraction and only parse the address`$unknownValue``string``'未知'`Fallback value for unmatched province/city/district`$level1Data``array``[]`Custom province data (see china-division format)`$level2Data``array``[]`Custom city data`$level3Data``array``[]`Custom district/county data**Batch Parsing Example:**

```
$addresses = [
    '张三 13512345678 北京市朝阳区望京SOHO 邮编100000',
    '李四 13800138000 上海市浦东新区陆家嘴金融中心88号',
];

foreach ($addresses as $raw) {
    $result = AddressParser::parse($raw);
    // Process each result...
}
```

Return Fields
-------------

[](#return-fields)

FieldTypeDescription`name``string`Full name`mobile``string`Phone number`idn``string`National ID number`postcode``string`Postal code`province``string`Province name`city``string`City name`region``string`District/county name`street``string`Street address (remaining text after removing province, city, and district)Use Cases
---------

[](#use-cases)

In real-world scenarios, user-submitted addresses are often unstructured. For example:

> 张三 13512345678 北京市朝阳区建国路88号 邮编100000

Manually parsing such strings is inefficient and error-prone. `hejunjie/address-parser` is designed specifically for these situations:

- Order address processing in e-commerce systems
- Address recognition in logistics and delivery services
- User profile completion in admin panels
- Address input validation in mini-programs and mobile apps

If you have any questions or suggestions, feel free to open an [issue](https://github.com/zxc7563598/php-address-parser/issues). I'll respond as soon as I can.

Acknowledgements
----------------

[](#acknowledgements)

The inspiration for this package came from a friend who mentioned the idea in an issue on one of my other repositories and kindly shared the [pupuk/address](https://github.com/pupuk/address) implementation. That spark led to `hejunjie/address-parser` — many thanks for the inspiration 🙌

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance93

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~113 days

Total

5

Last Release

35d ago

Major Versions

v1.0.3 → v2.0.02026-07-14

PHP version history (3 changes)v1.0.0PHP >=8.1

v1.0.3PHP >=7.0

v2.0.0PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/5b65d4b40ae456172fb38f63f84bf737ac88031484b1f228b1cc8d71baa80adf?d=identicon)[苏青安](/maintainers/%E8%8B%8F%E9%9D%92%E5%AE%89)

---

Top Contributors

[![zxc7563598](https://avatars.githubusercontent.com/u/46590942?v=4)](https://github.com/zxc7563598 "zxc7563598 (18 commits)")

---

Tags

address-extractionaddress-parserchina-addresscomposernatural-language-processingphpphp8shipping-addressessmart-parser

### Embed Badge

![Health badge](/badges/hejunjie-address-parser/health.svg)

```
[![Health](https://phpackages.com/badges/hejunjie-address-parser/health.svg)](https://phpackages.com/packages/hejunjie-address-parser)
```

###  Alternatives

[mwgg/airports

A JSON collection of ~29k entries with basic information about nearly every airport and landing strip in the world

7683.4k](/packages/mwgg-airports)[sauladam/shipment-tracker

Parses tracking information for several carriers, like UPS, USPS, DHL and GLS by simply scraping the data. No need for any kind of API access.

9845.4k](/packages/sauladam-shipment-tracker)[glauberportella/cnab-layouts-parser

Parser de arquivos de configuração CNAB gerados no projeto https://github.com/glauberportella/cnab-layouts

2154.5k](/packages/glauberportella-cnab-layouts-parser)[tcds-io/php-jackson

A lightweight, flexible object serializer for PHP, inspired by FasterXML/jackson

113.4k10](/packages/tcds-io-php-jackson)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)