Download the PHP package quangtam/vietnam-address-converter without Composer

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.

🌐 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
• 🟦 PHP: 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

• 🔄 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

Loại bỏ cấp Quận/Huyệ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):

Sau (2 cấp):

Ví dụ chuyển đổi:

Input:

Output:

🚀 Cài đặt

Yêu cầu hệ thống

• PHP >= 8.0
• Extension: json

Cài đặt qua Composer

Cài đặt thủ công

1. Clone repository:

2. Cài đặt dependencies:

🔧 Sử dụng cơ bản

1. Khởi tạo Converter

2. Chuyển đổi địa chỉ từ string

3. Chuyển đổi từ object

4. Xuất kết quả dưới dạng JSON

🔄 Các loại chuyển đổi

1. Merged (Gộp)

Nhiều phường/xã cũ được gộp thành một phường/xã mới:

2. Renamed (Đổi tên)

Phường/xã giữ nguyên ranh giới nhưng đổi tên:

3. Unchanged (Không đổi)

Phường/xã không có thay đổi:

📊 API Reference

VietnamAddressConverter

initialize(?string $dataPath = null): void

Khởi tạo converter với dữ liệu từ file JSON.

Tham số:

• $dataPath: Đường dẫn tới file dữ liệu JSON (tùy chọn)

convertAddress(string|FullAddress $address): ConversionResult

Chuyển đổi địa chỉ từ định dạng cũ sang mới.

Tham số:

• $address: Địa chỉ cần chuyển đổi (string hoặc FullAddress object)

Kết quả trả về:

• ConversionResult: Kết quả chuyển đổi

getDataStats(): array

Lấy thống kê dữ liệu.

getProvinces(): array

Lấy danh sách tất cả tỉnh/thành phố.

getWardsByProvince(string $provinceCode): array

Lấy danh sách phường/xã theo mã tỉnh.

searchMappings(string $keyword): array

Tìm kiếm mapping theo từ khóa.

Models

ConversionResult

FullAddress (Địa chỉ cũ có district)

NewAddress (Địa chỉ mới không có district)

💻 Ví dụ hoàn chỉnh

📊 Dữ liệu

Thư viện bao gồm:

• 34 tỉnh/thành phố theo cấu trúc hành chính mới
• 3,300+ phường/xã đã được cập nhật
• 10,000+ mapping records cho việc chuyển đổi

Dữ liệu được cập nhật theo Nghị quyết số 202/2025/QH15 của Quốc hội về việc sắp xếp đơn vị hành chính.

🛠️ Phát triển

Chạy tests

Kiểm tra code style

Sửa code style

Chạy ví dụ

🤝 Đóng góp

Chúng tôi hoan nghênh mọi đóng góp! Vui lòng:

1. Fork dự án
2. Tạo feature branch (git checkout -b feature/amazing-feature)
3. Commit thay đổi (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Mở Pull Request

📄 License

MIT License

📞 Liên hệ

• Issues: GitHub Issues
• Email: [email protected]

🙏 Cảm ơn

• Dữ liệu từ thanhtrungit97/dvhcvn
• Nghị quyết số 202/2025/QH15 của Quốc hội
• Tham khảo từ quangtam/vietnam-address-converter

Made with ❤️ for Vietnam developers