README

Laravel Addresses是一个包，允许您将地址与您的Laravel Eloquent模型关联。

功能

• 地址在变更时的自动地理编码，由Google Maps API提供
• 地址详情的验证（国家，邮编）
• ISO国家代码到国家名称的转换
• 存储地址元数据的能力 - 例如 ['type' => 'delivery', 'name' => 'home_address']

安装

要安装Laravel Addresses，只需运行以下Composer命令。

composer require divineomega/laravel-addresses

配置

运行以下Artisan命令以发布配置文件。

php artisan vendor:publish --provider="DivineOmega\LaravelAddresses\ServiceProvider" --force

这将创建默认的配置文件在config/addresses.php。

注意，默认情况下，您需要一个Google Maps API密钥才能提供地址地理编码和距离计算。如果您不希望使用地理编码，这可以在配置中禁用。

严格的地理编码

默认情况下，地理编码配置为“宽松的”；例如，如果给出了真实城市的名称，但邮编和街道地址指向一个不存在的地点，它将地理编码为该城市的中心。

在配置文件中将geocoding.strict标志设置为true，以在此场景中失败地理编码。

使用

将HasAddresses特征赋值给您希望关联地址的模型。例如，您可以像下面那样给默认的User模型地址。

<?php

namespace App;

use DivineOmega\LaravelAddresses\Traits\HasAddresses;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable, HasAddresses;

    /* ... */
}

检索地址

$addresses = $user->addresses()->get();

创建新地址

$user->addresses()->create([
    'line_1' => '10 Downing Street',
//  'line_2' => '',
    'town_city' => 'Westminster',
    'state_county' => 'London',
    'postcode' => 'SW1A 2AA',
    'country_code' => 'GBR',
]);

地理编码

创建或更新地址时自动进行地理编码。您可以使用isGeocoded方法检查地址是否已成功地理编码。

$address = $user->addresses()->first();

if ($address->isGeocoded()) {
    dd([$address->latitude, $address->longitude]);
}

如果需要，您还可以手动地理编码地址。

$address = $user->addresses()->first();
$address->geocode();
$address->save();

注意，地理编码可能会失败，在这种情况下，您可以通过尝试地理编码后检查地址是否已地理编码来检测它是否失败。

$address->geocode();

if (!$address->isGeocoded()) {
    // Handle geocoding failure here.
}

如果已设置现有的经纬度并地理编码失败，这些将被清除。

$address->geocode(); // Succeeds

// Change the address details here.

$address->geocode(); // Fails

// Latitude and longitude are now null.

验证

创建或更新地址时自动进行验证。如果验证失败，您可以预期抛出适当的异常。

• InvalidCountryException - 提供的country_code不是有效的ISO 3166-1 alpha-3国家代码。
• InvalidUKPostcodeException - 如果地址位于英国，提供的postcode不是有效的英国邮编。

如果需要，您还可以手动验证地址。

$address = $user->addresses()->first();

try {
    $address->validate();
} catch (\DivineOmega\LaravelAddresses\Exceptions\InvalidUKPostcodeException $e) {
    return back()->withErrors(['Invalid UK postcode.']);
}

距离计算

可以使用distanceTo方法计算两个不同地址之间的距离。

$address1 = $user->addresses[0];
$address2 = $user->addresses[1];

$distanceKilometres = $address1->distanceTo($address2);

默认情况下，计算直接距离（如飞鸟的距离）。如果您想，您可以指定不同的距离计算类型，例如驾驶距离。

use \DivineOmega\LaravelAddresses\DistanceStrategies\Driving;
use \DivineOmega\LaravelAddresses\DistanceStrategies\Walking;
use \DivineOmega\LaravelAddresses\DistanceStrategies\Cycling;

$drivingDistanceKm = $address1->distanceTo($address2, Driving::class);
$walkingDistanceKm = $address1->distanceTo($address2, Walking::class);
$cyclingDistanceKm = $address1->distanceTo($address2, Cycling::class);