README

🗒️ 描述

此包适用于依赖地理数据的应用程序。

默认情况下，它提供了 4 个模型：大陆、国家、区域、城市以及它们的翻译。

翻译由 nevadskiy/laravel-translatable 包提供。

此包还通过获取 GeoNames 服务提供的每日修改来保持数据最新，并使用这些修改来同步您的数据库。

🔌 安装

composer require nevadskiy/laravel-geonames

如果您打算使用翻译，您还需要安装一个额外的包。

composer require nevadskiy/laravel-translatable

✅ 要求

• Laravel 8.0 或更高版本
• PHP 7.3 或更高版本

🔨 使用

使用以下命令发布包资源

php artisan vendor:publish --tag=geonames-migrations --tag=geonames-models

播种

在播种之前，请确保您已运行数据库迁移。

php artisan migrate

然后，运行播种过程。

php artisan geonames:seed

它将下载 geonames 资源并将数据集插入到您的数据库中。

请注意，播种过程可能需要一些时间。平均而言，将带翻译的全数据集播种大约需要 40 分钟（不包括下载时间）。

如果您在播种过程中遇到内存泄漏问题，请查看 本节。

安排更新

如果您想接收 GeoNames 的每日更新，请将以下代码添加到 app/Console/Kernel.php 文件中。

GeoNames 每日更新在 UTC 时区的时间为 3:00 发布，因此为了确保它们已经可用，建议稍后运行命令。

protected function schedule(Schedule $schedule)
{
    $schedule->command('geonames:daily-update')->dailyAt('4:00');
}

请注意，指定的时间是针对 UTC 时区的。

同步

如果您错过了某些每日更新或只是决定更改播种器过滤器，您可以根据当前的 GeoNames 数据集同步数据库记录。

php artisan geonames:sync

此命令将创建缺失的记录，删除多余的记录，并根据当前数据集更新已修改的记录。

请注意，同步数据需要 geoname_id 和 alternate_name_id 字段。

自定义

如果您想自定义迁移或要导入的数据，您可以通过覆盖默认播种器来实现。

为此，请使用以下命令发布包播种器

php artisan vendor:publish --tag=geonames-seeders

发布包配置

php artisan vendor:publish --tag=geonames-config 

然后，在 config/geonames.php 文件中指定已发布的播种器

'seeders' => [
    Database\Seeders\Geo\ContinentSeeder::class,
    Database\Seeders\Geo\ContinentTranslationSeeder::class,
    Database\Seeders\Geo\CountrySeeder::class,
    Database\Seeders\Geo\CountryTranslationSeeder::class,
    Database\Seeders\Geo\DivisionSeeder::class,
    Database\Seeders\Geo\DivisionTranslationSeeder::class,
    Database\Seeders\Geo\CitySeeder::class,
    Database\Seeders\Geo\CityTranslationSeeder::class,
]

过滤

为了减少数据库大小，您可以为播种设置过滤器，仅导入您应用程序中真正需要的数据。

例如，您可以设置城市的最低人口。所有人口较少的城市将不会被导入。

要这样做，覆盖 CitySeeder 类中的 $minPopulation 属性。

为了完全控制这种行为，覆盖播种器的 filter 方法。

属性映射

要向表中添加自定义字段，您还需要告诉播种器如何使用 mapAttributes 方法填充这些字段。

《mapAttributes》方法应返回数据库记录的所有属性，包括时间戳，因为在播种过程中不会触发模型事件，因为该包使用批量插入策略。但是，所有模型铸造器和转换器将按常规应用。

例如，如果您想使用UUID作为主键，可以按以下方式扩展原始播种器

<?php

namespace Database\Seeders\Geo;

use App\Models\Geo\City;
use Illuminate\Support\Str;use Nevadskiy\Geonames\Seeders\CitySeeder as Seeder;

class CitySeeder extends Seeder
{
    /**
     * {@inheritdoc}
     */
    protected static $model = City::class;

    /**
     * {@inheritdoc}
     */
    protected function mapAttributes(array $record): array
    {
        return array_merge(parent::mapAttributes($record), [
            'id' => (string) Str::uuid(),
        ]);
    }
}

自定义播种器

对于结构的大幅更改，您可以添加自己的播种器或扩展现有的播种器。

每个播种器都必须实现《Nevadskiy\Geonames\Seeders\Seeder》接口。

在《geonames》配置文件中指定的所有播种器将按指定顺序依次执行。

翻译

要使用翻译，您需要安装《a href="https://github.com/nevadskiy/laravel-translatable" rel="nofollow noindex noopener external ugc">nevadskiy/laravel-translatable

阅读其《a href="https://github.com/nevadskiy/laravel-translatable/wiki" rel="nofollow noindex noopener external ugc">文档以了解更多关于它的工作方式。您还可以使用它来处理其他模型的翻译。

否则，您仍然可以不使用翻译来使用该包，只需简单删除以下内容

• 翻译迁移
• 翻译播种器（从《geonames》配置文件中删除）
• 从已发布模型中删除《HasTranslations》特性和《translatable》属性

内存泄漏

与播种大量数据相关联的最常见问题之一是内存泄漏。

此包使用PHP生成器和《a href="https://laravel.net.cn/docs/9.x/collections#lazy-collection-introduction" rel="nofollow noindex noopener external ugc">延迟集合读取文件，以避免将整个文件加载到内存中。

然而，有些包在长时间运行命令期间将数据库查询和模型事件记录到内存中，导致内存泄漏。

有关如何避免与以下包一起工作时发生内存泄漏的说明

Laravel Ignition

使用《code>php artisan vendor:publish --tag=flare-config发布flare配置。

在《flare.php》配置文件中将《code>report_query_bindings设置为《code>false，如下所示

'flare_middleware' => [
    ...
    AddQueries::class => [
        'maximum_number_of_collected_queries' => 200,
        'report_query_bindings' => false,
    ],
    ...
]

Laravel Telescope

更新《telescope.php》配置文件，如下所示

'ignore_commands' => [
    'geonames:seed',
    'geonames:daily-update',
    'geonames:sync',
]

📑 更新日志

请参阅《a href="https://github.com/nevadskiy/laravel-geonames/blob/HEAD/CHANGELOG.md" rel="nofollow noindex noopener external ugc">更新日志以获取有关最近更改的更多信息。

☕ 贡献

请参阅《a href="https://github.com/nevadskiy/laravel-geonames/blob/HEAD/.github/CONTRIBUTING.md" rel="nofollow noindex noopener external ugc">CONTRIBUTING以获取更多信息。

📜 许可证

《MIT》许可证。请参阅《a href="https://github.com/nevadskiy/laravel-geonames/blob/HEAD/LICENSE" rel="nofollow noindex noopener external ugc">LICENSE以获取更多信息。