PHPackages                             quangtam/vietnam-address-converter - 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. [Utility & Helpers](/categories/utility)
4. /
5. quangtam/vietnam-address-converter

ActiveLibrary[Utility & Helpers](/categories/utility)

quangtam/vietnam-address-converter
==================================

A PHP library to convert and standardize Vietnamese addresses, provinces, districts, and wards with mapping capabilities

v1.1.0(10mo ago)0212MITPHPPHP >=8.0

Since Jul 12Pushed 10mo agoCompare

[ Source](https://github.com/quangtam/vietnam-address-converter-php)[ Packagist](https://packagist.org/packages/quangtam/vietnam-address-converter)[ RSS](/packages/quangtam-vietnam-address-converter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (3)Versions (4)Used By (0)

Vietnam Address Converter PHP
=============================

[](#vietnam-address-converter-php)

Thư viện PHP để tự động chuyển đổi địa chỉ hành chính Việt Nam từ cũ sang mới theo Nghị quyết số 202/2025/QH15 của Quốc hội.

[![Packagist Version](https://camo.githubusercontent.com/8ad39ec50ac3e0234ee75878f9dcb11c918a7b41587d51a5dfddcef62aec2487/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7175616e6774616d2f766965746e616d2d616464726573732d636f6e7665727465722e737667)](https://packagist.org/packages/quangtam/vietnam-address-converter)[![PHP Version](https://camo.githubusercontent.com/f32695bd6f65b12545162e869707d33dac6bcb5f6e5dc0d48b6d1f8162b6c247/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e302d626c75652e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Tests](https://camo.githubusercontent.com/3ab4882a1b7d64e5eb5168ad0b0b9cdfd53f59f114ee5f727958504214a5789c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e2e737667)](tests/)

🌐 Multi-Language Support
------------------------

[](#-multi-language-support)

Vietnam Address Converter hiện có sẵn cho nhiều ngôn ngữ lập trình:

- 🟨 **JavaScript/TypeScript**: [vietnam-address-converter](https://github.com/quangtam/vietnam-address-converter)
- 🟦 **PHP**: [vietnam-address-converter-php](https://github.com/quangtam/vietnam-address-converter-php) - Thư viện PHP với API tương tự (repo này)
- 🔴 **Python**: Coming soon...
- 🟩 **Go**: Coming soon...

💡 **Tất cả implementations đều sử dụng cùng dữ liệu mapping và logic chuyển đổi để đảm bảo tính nhất quán.**

✨ Tính năng chính
-----------------

[](#-tính-năng-chính)

- 🔄 **Chuyển đổi địa chỉ tự động**: Chuyển đổi địa chỉ cũ sang địa chỉ mới theo quy định mới nhất
- 📊 **Dữ liệu mapping thực tế**: Sử dụng dữ liệu mapping chính thức từ cơ sở dữ liệu hành chính
- 🎯 **Cấu trúc hành chính mới**: Loại bỏ cấp quận/huyện theo Nghị quyết 202/2025/QH15
- 🔍 **Tìm kiếm thông minh**: Tìm kiếm và mapping địa chỉ với độ chính xác cao
- ⚡ **Hiệu suất cao**: Xử lý nhanh với caching tối ưu
- 📱 **Dễ sử dụng**: API đơn giản và dễ tích hợp

📈 Thay đổi quan trọng
---------------------

[](#-thay-đổi-quan-trọng)

### Loại bỏ cấp Quận/Huyện

[](#loại-bỏ-cấp-quậnhuyện)

Theo Nghị quyết 202/2025/QH15, cấu trúc hành chính mới không còn cấp quận/huyện:

**Trước (3 cấp):**

```
Tỉnh/Thành phố → Quận/Huyện → Phường/Xã

```

**Sau (2 cấp):**

```
Tỉnh/Thành phố → Phường/Xã

```

**Ví dụ chuyển đổi:**

Input:

```
Phường 12, Quận Gò Vấp, Thành phố Hồ Chí Minh

```

Output:

```
Phường An Hội Tây, Thành phố Hồ Chí Minh  // Không còn "Quận Gò Vấp"

```

🚀 Cài đặt
---------

[](#-cài-đặt)

### Yêu cầu hệ thống

[](#yêu-cầu-hệ-thống)

- PHP >= 8.0
- Extension: json

### Cài đặt qua Composer

[](#cài-đặt-qua-composer)

```
composer require quangtam/vietnam-address-converter
```

*Database sẽ được tự động tải từ package `quangtam/vietnam-address-database`*

### Cài đặt thủ công

[](#cài-đặt-thủ-công)

1. Clone repository:

```
git clone https://github.com/quangtam/vietnam-address-converter-php
cd vietnam-address-converter-php
```

2. Cài đặt dependencies:

```
composer install
```

🔧 Sử dụng cơ bản
----------------

[](#-sử-dụng-cơ-bản)

### 1. Khởi tạo Converter

[](#1-khởi-tạo-converter)

```