Chuyển tới nội dung chính
Phiên bản: 8.4.0

Location

File: packages/skilldo/cms/src/Location/Location.php
Class: SkillDo\Cms\Location\Location
Alias: \SkillDo\Location (đăng ký trong CmsServiceProvider)

Location là một công cụ mạnh mẽ cho việc truy xuất thông tin địa lý cơ bản của Việt Nam, bạn có thể dễ dàng truy cập thông tin về các tỉnh thành, quận huyện và các đơn vị hành chính cấp dưới như phường, xã.

Dữ liệu được lấy từ dịch vụ SkillDo (SKDService::location()) và cache 30 ngày. Các phần tử trả về là object (stdClass); các method *Options() chỉ trả về đơn vị có active = true.

Đây là dữ liệu đơn vị hành chính cũ (3 cấp: tỉnh → quận/huyện → phường/xã). Với đơn vị hành chính mới áp dụng từ 01/07/2025 (2 cấp), dùng Location2.

Tỉnh / Thành phố​

Danh sách​

Lấy danh sách Thành phố trực thuộc Trung ương

\SkillDo\Location::provinces()

Kết quả

{
    "0": {
        "id": 58,
        "name": "Hồ Chí Minh",
        "fullname": "TP. Hồ Chí Minh",
        "keywords": [
            "HCM",
            "Hcm",
            "Sài gòn",
            "TP.HCM"
        ],
        "active": true
    },
    "1": {
        "id": 24,
        "name": "Hà Nội",
        "fullname": "Hà Nội",
        "active": true
    },
    ...
}

Options​

Lấy danh sách theo dạng options

\SkillDo\Location::provincesOptions()

Kết quả

[
    58 => 'TP. Hồ Chí Minh',
    24 => 'Hà Nội',
    1 => 'Tỉnh An Giang',
    2 => 'Tỉnh Bà Rịa - Vũng Tàu',
    3 => 'Tỉnh Bắc Giang',
    4 => 'Tỉnh Bắc Kạn',
    5 => 'Tỉnh Bạc Liêu',
    ...
]

Chi tiết​

Lấy chi tiết tỉnh thành phố theo id

\SkillDo\Location::provinces(58)

Kết quả

{
    "id": 58,
    "name": "Hồ Chí Minh",
    "fullname": "TP. Hồ Chí Minh",
    "keywords": [
        "HCM",
        "Hcm",
        "Sài gòn",
        "TP.HCM"
    ],
    "active": true
}

Tên​

Lấy tên tỉnh thành phố

\SkillDo\Location::provinceName(58) // TP. Hồ Chí Minh

Quận / Huyện / Thị xã / Thành phố​

Danh sách​

Lấy danh sách quận huyện theo id tỉnh / thành phố

\SkillDo\Location::districts($province_id = null)

Kết quả

{
    "0": {
        "id": 6440,
        "name": "Huyện Bình Chánh",
        "fullname": "Huyện Bình Chánh",
        "province_id": 58,
        "province_name": "TP. Hồ Chí Minh",
        "active": true
    },
    "1": {
        "id": 6441,
        "name": "Huyện Cần Giờ",
        "fullname": "Huyện Cần Giờ",
        "province_id": 58,
        "province_name": "TP. Hồ Chí Minh",
        "active": true
    },
    ...
}

Options​

Lấy danh sách theo dạng options

\SkillDo\Location::districtsOptions(58)

Kết quả

[
    6440 => 'Huyện Bình Chánh',
    6441 => 'Huyện Cần Giờ',
    ...
]

Chi tiết​

Lấy chi tiết quận huyện theo id

\SkillDo\Location::districts(58, 6440); //Huyện Bình Chánh

kêt quả

{
  "id": 6440,
  "name": "Huyện Bình Chánh",
  "fullname": "Huyện Bình Chánh",
  "province_id": 58,
  "province_name": "TP. Hồ Chí Minh",
  "active": true
}

Tên​

Lấy tên quận huyện bằng id tỉnh thành và id quận huyện

\SkillDo\Location::districtName(58, 6440); //Huyện Bình Chánh

Phường / Xã / Thị trấn / Thôn / Đội​

Danh sách​

Lấy danh sách Phường xã theo id quận huyện

\SkillDo\Location::wards($district_id = null)

Kết quả

{
    "0": {
        "id": 83331,
        "name": "Xã Tân Kiên",
        "fullname": "Xã Tân Kiên",
        "district_id": 6440,
        "district_name": "Huyện Bình Chánh",
        "active": true
    },
    "1": {
        "id": 83332,
        "name": "Xã An Phú Tây",
        "fullname": "Xã An Phú Tây",
        "district_id": 6440,
        "district_name": "Huyện Bình Chánh",
        "active": true
    }
}

Options​

Lấy danh sách theo dạng options

\SkillDo\Location::wardsOptions(6440)

Kết quả

[
    83331 => 'Xã Tân Kiên',
    83332 => 'Xã An Phú Tây',
    ...
]

Chi tiết​

Lấy chi tiết phường xã theo id quận huyện và id phường xã

\SkillDo\Location::wards(6440, 83331); //Xã Tân Kiên

kêt quả

{
    "id": 83331,
    "name": "Xã Tân Kiên",
    "fullname": "Xã Tân Kiên",
    "district_id": 6440,
    "district_name": "Huyện Bình Chánh",
    "active": true
}

Tên​

Lấy tên phường xã bằng id quận huyện và id phường xã

\SkillDo\Location::wardName(6440, 83331); //Xã Tân Kiên

Địa chỉ đầy đủ​

Ghép tên Phường xã + Quận huyện + Tỉnh thành thành chuỗi địa chỉ hoàn chỉnh:

\SkillDo\Location::address($province_id, $districts_id, $ward_id = '')
\SkillDo\Location::address(58, 6440, 83331);
// "Xã Tân Kiên, Huyện Bình Chánh, TP. Hồ Chí Minh"