README

本包提供了一种简单的方式，通过常规模型和关系，在 Laravel 中与越南行政区划进行交互。

最后更新越南行政区划 CSV 文件是在 2023 年 5 月 13 日

安装

您可以通过 composer 安装此包

composer require dileedotdev/laravel-vietnamese-administrative-units

您应该使用以下命令发布并运行迁移

php artisan vendor:publish --tag="vietnamese-administrative-units-migrations"
php artisan migrate

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="vietnamese-administrative-units-config"

以下是已发布配置文件的内容

return [
    'province' => [
        'model' => \VietnameseAdministrativeUnits\Models\Province::class,
        'table' => 'provinces',
    ],

    'district' => [
        'model' => \VietnameseAdministrativeUnits\Models\District::class,
        'table' => 'districts',
    ],

    'ward' => [
        'model' => \VietnameseAdministrativeUnits\Models\Ward::class,
        'table' => 'wards',
    ],
];

用法

如你所见，该包提供了 3 个模型：Province、District 和 Ward。每个模型都使用软删除。（因为在越南，行政区划未来可能会发生变化）

导入数据

首先，您需要将行政区划导入到数据库中。您可以使用以下命令

php artisan vietnamese-administrative-units:import

默认情况下，此命令将使用放置在 ./assets/vietnamese-administrative-units.csv 的 CSV 文件。您可以通过传递文件路径作为参数来更改该文件。

php artisan vietnamese-administrative-units:import /home/dilee/Downloads/vietnamese-administrative-units.csv

如果您想知道 CSV 文件从何而来，您可以在这里检查“Quận Huyện, Phường Xã”，然后点击“Xuất Excel”下载 Excel 文件。接下来，您应该手动将 Excel 文件转换为 CSV 文件，而不更改任何数据。

使用模型

您可以使用模型如常使用

use VietnameseAdministrativeUnits\Models\Ward;

class YourModel {
    public function ward()
    {
        return $this->belongsTo(
            config('vietnamese-administrative-units.ward.model', Ward::class)
        )->withTrashed();
    }
}

如我之前所说，每个模型都使用软删除，因此您应该使用 withTrashed() 来获取关系，而不管模型是否被删除。

并且不要忘记在迁移中定义外键

return new class extends Migration
{
    public function up()
    {
        Schema::table('your_table', function (Blueprint $table) {
            $table->foreignId('ward_id')->constrained();
        });
    }
}

以下是一些有用的代码

use VietnameseAdministrativeUnits\Models\Province;
use VietnameseAdministrativeUnits\Models\District;
use VietnameseAdministrativeUnits\Models\Ward;

// Get all provinces
Province::all();

// Get all districts
District::all();

// Get all wards
Ward::all();

我可以多次使用导入命令吗？

是的，您可以。该命令足够智能，可以检查行政区划是否已在数据库中，将跳过该单位，并软删除任何不在 CSV 文件中的单位。

如果提供的 CSV 文件过时了，我应该怎么办？

我将定期更新 CSV 文件，因此很少需要您自己更新 CSV 文件。但如果 CSV 文件过时了，您可以采取以下解决方案

首先，该命令可以接收自定义的 CSV 文件路径，因此您可以下载新的 CSV 文件并将其传递给命令。

其次，您可以去此包的 GitHub 仓库，创建一个 pull request 来更新 CSV 文件，我会尽快合并。

最后，如果上述解决方案对您来说太复杂了，您可以在 GitHub 上创建一个问题来提醒我更新 CSV 文件。

测试

composer test

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG

贡献

有关详细信息，请参阅 CONTRIBUTING

安全漏洞

请查看我们的安全策略了解如何报告安全漏洞。

致谢

许可协议

MIT许可证。请参阅许可证文件获取更多信息。

dileedotdev / laravel-vietnamese-administrative-units

维护者

详细信息