README

使用各种服务从访客的IP地址获取其位置。

• 需求
• 安装
• 使用
• 驱动程序
• 从v6升级
• 版本控制

需求

• PHP >= 8.1
• Laravel >= 8.0

安装

使用 composer require 安装位置

composer require stevebauman/location

发布配置文件（这将创建一个位于 config 目录中的 location.php 文件）

php artisan vendor:publish --provider="Stevebauman\Location\LocationServiceProvider"

使用

检索客户端的位置

use Stevebauman\Location\Facades\Location;

if ($position = Location::get()) {
    // Successfully retrieved position.
    echo $position->countryName;
} else {
    // Failed retrieving position.
}

重要:

• 此方法通过 request()->ip() 获取用户的IP地址。
• 在默认配置中，testing.enabled 处于活动状态，返回的IP地址在美国。禁用它以获取客户端的真实IP地址。

检索特定IP地址的位置

$position = Location::get('192.168.1.1');

驱动程序

可用驱动程序

可用驱动程序

• IpApi - 默认
• IpApiPro
• IpData
• IpInfo
• Kloudend
• GeoPlugin
• MaxMind
• Cloudflare
• IP2Location.io

使用自托管数据库设置MaxMind（可选）

我们鼓励使用本地数据库（如上所述）将MaxMind设置为后备驱动程序，因为它允许您绕过使用外部Web服务可能发生的任何限制。

要设置MaxMind以从您的服务器检索用户的地理位置，您必须

1. 创建一个 maxmind帐户 并登录
2. 从个人资料菜单下拉菜单中点击“管理许可证密钥”
3. 生成新的许可证密钥
4. 复制许可证密钥并将其保存到您的 .env 文件中，使用 MAXMIND_LICENSE_KEY 键
5. 运行 php artisan location:update 以将最新的 .mmdb 文件下载到您的 database/maxmind 目录
6. 这就完成了，您已经设置好了！

注意：请记住，您需要定期运行 location:update 以更新此文件，以便从访客获取最新的信息。

后备驱动程序

在配置文件中，您可以指定任意数量的后备驱动程序。建议配置MaxMind驱动程序使用本地数据库 .mmdb 文件（如上所述），这样您始终可以检索访客的一些通用位置信息。

如果在尝试获取驱动程序时发生异常（例如，如果提供商的API更改导致的400/500错误），它将自动使用下一个驱动程序。

创建自己的驱动程序

要创建自己的驱动程序，只需在应用程序中创建一个类，并扩展抽象类 Driver

namespace App\Location\Drivers;

use Illuminate\Support\Fluent;
use Illuminate\Support\Facades\Http;
use Stevebauman\Location\Position;
use Stevebauman\Location\Request;
use Stevebauman\Location\Drivers\Driver;

class MyDriver extends Driver
{    
    protected function process(Request $request): Fluent
    {
         $response = Http::get("https://driver-url.com", ['ip' => $request->getIp()]);
         
         return new Fluent($response->json());
    }

    protected function hydrate(Position $position, Fluent $location): Position
    {
        $position->countryCode = $location->country_code;

        return $position;
    }
}

然后，将您的驱动程序类名称插入配置文件

// config/location.php

'driver' => App\Location\Drivers\MyDriver::class,

从v6升级

在版本7中，代码库已更新为严格的PHP类型，更新了PHP和Laravel版本要求，更新了 Driver 结构，以及一些小的配置添加。

配置

在版本7中，位置驱动程序现在可以实现 Updatable 接口，允许它们使用 location:update 命令进行更新。目前，只有MaxMind驱动程序支持此功能。

要将配置文件更新为能够自动下载最新的MaxMind数据库文件，请将以下 url 配置选项插入到您的 config/location.php 文件中

// config/location.php

return [
    'maxmind' => [
        // ...
        
        'local' => [
            // ...
            
+            'url' => sprintf('https://download.maxmind.com/app/geoip_download_by_token?edition_id=GeoLite2-City&license_key=%s&suffix=tar.gz', env('MAXMIND_LICENSE_KEY')),
        ],
    ],
];

完成之后，您可以执行以下Artisan命令来下载最新的.mmdb文件

php artisan location:update

驱动程序

在版本7中，代码库已经更新为严格的PHP类型，更新了PHP和Laravel版本要求，以及更新的Driver结构。

如果您已经创建了自定义的驱动实现，您必须更新它以使用基础Driver或HttpDriver类。

如果您正在使用HTTP服务获取位置，扩展HttpDriver可能有助于减少您需要编写的代码。

namespace App\Location\Drivers;

use Illuminate\Support\Fluent;
use Stevebauman\Location\Position;
- use Stevebauman\Location\Drivers\Driver;
+ use Stevebauman\Location\Drivers\HttpDriver;

- class MyDriver extends Driver
+ class MyDriver extends HttpDriver
{
-    public function url($ip)
+    public function url(string $ip): string;
    {
        return "http://driver-url.com?ip=$ip";
    }
    
-    protected function process($ip)
-    {
-        return rescue(function () use ($ip) {
-            $response = json_decode(file_get_contents($this->url($ip)), true);
-            
-            return new Fluent($response);
-        }, $rescue = false);
-    }

-    protected function hydrate(Position $position, Fluent $location)
+    protected function hydrate(Position $position, Fluent $location): Position;
    {
        $position->countryCode = $location->country_code;

        return $position;
    }
}

版本控制

尽可能按照语义版本控制指南对位置进行版本控制。

版本号将以以下格式编号

<major>.<minor>.<patch>

并且按照以下指南构建

• 破坏向后兼容性会导致主版本号增加，并将次版本号和修补程序重置。
• 不破坏向后兼容性的新功能会增加次版本号，并将修补程序重置。
• 错误修复和杂项更改会增加修补程序。

不单独维护次版本，我们鼓励您升级到下一个次版本。

主版本通过单独的分支进行维护。