README

概览

LinterLocations 包是 Laravel 应用中管理地理位置的综合解决方案。它提供从大陆到具体地址的地理实体的结构化层次，并通过数据库模式简化了它们的管理。

此包依赖强大的管理面板 FilamentPHP 来提供其图形用户界面 (GUI)。对 FilamentPHP 的依赖使得用户可以通过一个复杂且直观的界面轻松管理这些地理实体。

版本兼容性

Laravel 兼容性

我们的包旨在与 Laravel 无缝协作。以下是与我们的包兼容的 Laravel 版本

Laravel 10.x

FilamentPHP 兼容性

由于我们的包依赖于 FilamentPHP 来提供其 GUI 功能，因此确保兼容性至关重要。我们的包与以下 FilamentPHP 版本兼容

FilamentPHP 3.x

PHP 版本

此外，我们的包需要 PHP 版本 8.1 或更高。

安装

您可以通过 composer 安装此包

composer require pardalsalcap/linter-locations

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="linter-locations-migrations"
php artisan migrate

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

php artisan vendor:publish --tag="linter-locations-config"

这是已发布配置文件的内容

return [
    'available_locales' => [
        'ca' => 'Català',
        'es' => 'Castellano',
        'en' => 'English',
    ],
    'use_scoped_search' => true,
];

配置细节

发布配置文件后，您可以自定义以下设置

available_locales：定义您的应用程序将支持的语言列表。这对于包的翻译功能至关重要。
use_scoped_search：此布尔值设置启用范围搜索功能。当设置为 true 时，搜索将更加关注 json 字段。

这些设置允许您根据应用程序的具体需求调整包的行为。

FilamentPHP 依赖和 GUI 管理

依赖 FilamentPHP

我们的包需要 FilamentPHP 管理面板来提供其 GUI 功能。FilamentPHP 为管理地理实体提供了一个优雅的行政界面。

包将安装 filamentphp 到您的应用程序中

管理实体

此包提供直观的 GUI 来管理各种实体，如大陆、国家、社区、州、城市和地址。此 GUI 是 FilamentPHP 管理面板的一部分，为数据管理提供用户友好的体验。

数据库结构

表和字段

大陆

id：主键。
lat & lon：地理坐标（纬度和经度）的小数字段。
iso：唯一标识大陆的两字母 ISO 代码。
name：大陆名称。
translations：存储名称翻译的 JSON 字段。
created_at & updated_at：时间戳。

国家

id：主键。
continent_id：对大陆表的外键。
lat & lon：地理坐标。
iso：两字母 ISO 国家代码。
iso3：三字母 ISO 国家代码。
name：国家名称。
translations：存储名称翻译的 JSON 字段。
时间戳。

社区

id：主键。
country_id：对国家表的外键。
地理坐标、ISO 代码、名称、翻译。
时间戳。

州

id：主键。
country_id 和 community_id：外键。
地理坐标、ISO 代码、名称、翻译。
时间戳。

城市

id：主键。
state_id：对州表的外键。
地理坐标、邮编、名称、翻译。
时间戳。

地址

id：主键。
city_id：对城市表的外键。
地理坐标、邮政编码、详细地址字段。
时间戳。

可寻址对象

address_id：地址表的外键。
addressable_id 和 addressable_type：用于多态关系。
address_type：地址类型（例如，'家庭'、'工作'）。
外键约束。

关系

大陆有许多国家。
国家属于一个大陆，并有多个社区。
社区属于一个国家，并有多个州。
州同时属于一个国家和一个社区，并有多个城市。
城市属于一个州，并有多个地址。
地址属于一个城市，可以通过 Addressables 多态关系与各种模型（用户、企业等）相关联。

使用说明

在各种表中的 translations 字段应用于存储不同语言的名翻译。
将这些数据插入到这些表中时，请确保值符合各自的标准，尤其是ISO代码和地理坐标。
addressables 表提供了一种灵活的方式来将地址与不同类型的实体相关联。它是一个多态关系，允许各种使用场景。

示例用法

// Example of associating a user with an address
$user = User::find(1);
$address = Address::find(1);

$user->addresses()->attach($address->id, ['address_type' => 'home']);

HasAddresses 特性

概览

pardalsalcap/linter-locations 包提供的 HasAddresses 特性旨在与 Laravel 应用中的 Eloquent 模型一起使用。它使模型能够与 addresses 表交互，允许将地址关联、附加和分离到任何 Eloquent 模型。

用法

要使用 HasAddresses 特性，只需将其包含在任何应具有可寻址关系的 Eloquent 模型中。这允许模型轻松管理相关地址。

方法

addresses()：一个多态多对多关系方法，返回与模型关联的地址。
attachAddress(Address $address)：将地址附加到模型。如果地址已附加，则不会创建重复条目。
detachAddress(Address $address)：从模型中分离现有地址。
syncAddresses(...$addresses)：将给定的地址列表与模型同步，附加新地址并分离不在提供列表中的地址。

示例

以下是如何在用户模型中使用 HasAddresses 特性的示例

use Illuminate\Database\Eloquent\Model;
use Pardalsalcap\LinterLocations\Traits\HasAddresses;

class User extends Model
{
    use HasAddresses;

    // User model methods and properties
}

$user = User::find(1);
$address = Address::find(1);

// Attach an address to the user
$user->attachAddress($address);

// Detach an address from the user
$user->detachAddress($address);

// Sync addresses (attach new ones and detach others)
$addresses = Address::whereIn('id', [1, 2, 3])->get();
$user->syncAddresses($addresses);

在 Filament 中自定义和翻译 GUI

概览

pardalsalcap/linter-locations 包允许您通过 Filament 管理面板管理地理实体，如大陆、国家等。为了满足不同语言或特定的措辞偏好，您可以发布和自定义这些实体的翻译文件。

发布翻译文件

要自定义大陆管理界面（或任何其他实体）的翻译，请按照以下步骤操作

发布翻译文件：使用以下 Artisan 命令将翻译文件发布到应用程序的 resources/lang/vendor/linter-locations 目录
```
php artisan vendor:publish --tag=linter-locations-translations
```

此命令将包中的默认翻译文件复制到您的应用程序中，允许您进行修改。

目前我们有英文、西班牙语和加泰罗尼亚语的翻译。

修改翻译

发布后，您可以在 resources/lang/vendor/linter-locations 下找到翻译文件。以下是大陆的文件结构示例

/resources
└── /lang
    └── /vendor
        └── /linter-locations
            └── /es
                └── continents.php

您可以编辑这些文件以更改现有翻译或添加新语言。

示例：自定义大陆翻译

以下是大陆.php 翻译文件的片段

<?php

return [
    'navigation' => 'Continentes',
    'model_label' => 'Continente',
    'model_label_plural' => 'Continentes',
    'iso_field' => 'Código ISO2',
    'name_field' => 'Nombre',
    'lat_field' => 'Latitud',
    'lon_field' => 'Longitud',
    'translations_field' => 'Traducción al :l',
    'iso_column' => 'Código ISO',
    'name_column' => 'Nombre',
    'lat_column' => 'Latitud',
    'lon_column' => 'Longitud',
    'navigation_group' => 'Localizaciones',
];

根据需要编辑这些翻译。例如，要将翻译为法语，请在 resources/lang/vendor/linter-locations 内创建一个 fr 文件夹，并复制 continents.php 文件及其法语翻译。

欢迎翻译贡献。

LinterLocations 安装命令

概览

linter-locations:install 命令由 pardalsalcap/linter-locations 包提供，自动设置数据库并填充必要的地理数据。这包括大陆、国家、社区（专注于西班牙地区）、州（西班牙省份）和城市（西班牙市镇）。运行此命令可以轻松设置包含结构化地理数据层次结构的数据库，这对于处理基于位置信息的应用至关重要。

命令用法

要执行安装命令，请在您的 Laravel 项目中运行以下命令

php artisan linter-locations:install

命令功能

运行此命令时，将执行几个关键操作

加载配置： 加载包的配置设置，包括可用的区域设置和回退区域设置。
数据库填充： 1. 提示您确认是否填充数据库。2. 从 JSON 文件安装并填充大陆表。3. 安装并填充国家表，包括它们各自的大陆映射。4. 通过分别填充社区、州和城市表来安装西班牙社区、州和城市。

设置 Filament GUI 进行实体管理

概览

要使用 Filament 为 pardalsalcap/linter-locations 包提供的 GUI 来管理地理实体，用户必须为要管理的每个实体创建一个资源文件。这些资源文件应放在 Laravel 应用的 app/Filament/Resources 目录中。

创建 Filament 资源

以下是创建实体资源文件的步骤指南

导航到资源目录：首先，转到您的 Laravel 应用中的 app/Filament/Resources 目录。如果目录不存在，请创建它。
创建资源文件：对于您想要通过 Filament 管理的每个实体，创建一个新的 PHP 类，该类扩展了来自 pardalsalcap/linter-locations 包的相应资源类。

示例：创建大陆资源

以下是一个为 Continent 实体创建资源文件的示例

<?php
namespace App\Filament\Resources;

class ContinentResource extends \Pardalsalcap\LinterLocations\Resources\ContinentResource
{
    // Customizations (if any) go here
}

您可以在 /resources/stubs 中找到扩展所有可用资源类的示例

AddressableRelationManager

概览

AddressableRelationManager 是来自 Linter Locations 包的定制关系管理器，用于处理 Filament PHP 资源中的地址相关功能。它与实现 HasAddresses 特性的模型一起使用。

功能

表单模式：提供用于管理地址详细信息的表单，包括类型、街道地址、号码、楼梯、楼层、门、国家、州和城市。
表格配置：以表格视图显示与模型关联的地址，包括创建、编辑、附加、分离和删除地址的选项。
动态选择字段：州和城市字段根据选定的国家动态更新。
自定义操作：包括创建新地址、附加现有地址、编辑和删除等操作。
批量操作：支持批量删除操作。

用法

要在 Filament 资源中使用 AddressableRelationManager，请确保您的模型使用 HasAddresses 特性。此特性提供将地址附加、分离和同步到模型的方法。

在您的 Filament 资源中，然后可以包含 AddressableRelationManager 来管理链接到您的模型的地址。

示例

以下是在 Filament 资源中使用 AddressableRelationManager 的基本示例

namespace App\Filament\Resources;

use App\Models\YourModel;
use Pardalsalcap\LinterLocations\Resources\AddressResource\RelationManagers\AddressableRelationManager;

class YourModelResource extends \Filament\Resources\Resource
{
    public static function getRelations(): array
    {
        return [
            AddressableRelationManager::class,
        ];
    }

    // Other resource configurations...
}

致谢

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。

pardalsalcap / linter-locations

维护者

详细信息