README

🌍 - 将IP地址转换为地理位置

本包将帮助您获取访问者的国家。

本包解决了哪些问题？

根据您应用程序的上下文，您可能希望显示针对访问者特定国家/地区的定制内容。如果这是用户的首次访问，本包将帮助提供合理的默认值，使用IP地址。

安装

您可以通过composer安装此包

composer require dive-be/laravel-geo

如果您打算使用他们的服务，则需要安装GeoIP2

composer require geoip2/geoip2

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

php artisan geo:install

这是配置文件的内容

return [
    /**
     * IP address translations can be cached to improve successive lookup times.
     */
    'cache' => [
        'enabled' => false,

        /**
         * Address translations are tagged to only clear them when a clear command is run.
         * Not supported by the "file", "database" and "dynamodb" cache drivers.
         */
        'tag' => 'dive-geo-location',

        /**
         * Time-to-live in seconds.
         */
        'ttl' => 3600,
    ],

    /**
     * Detectors are classes responsible for detecting the geo location of a given IP address.
     *
     * Supported drivers:
     *  - "static" (always translates to the fallback country)
     *  - "maxmind_db" (GeoIP2/GeoLite2 Databases)
     *  - "maxmind_web" (GeoIP2 Precision Web Services)
     *  - "ip2c" (IP 2 Country free web service)
     */
    'detectors' => [
        'driver' => env('GEO_DETECTORS_DRIVER', 'static'),

        'ip2c' => [
            'endpoint' => 'https://api.ip2country.info/ip',
        ],

        'maxmind_db' => [
            'database_path' => storage_path('app/geoip2.mmdb'),
            'license_key' => env('GEO_DETECTORS_MAXMIND_DB_LICENSE_KEY'),
            'url' => 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=%s&suffix=tar.gz',
        ],

        'maxmind_web' => [
            'account_id' => env('GEO_DETECTORS_MAXMIND_WEB_ACCOUNT_ID'),
            'license_key' => env('GEO_DETECTORS_MAXMIND_WEB_LICENSE_KEY'),
        ],
    ],

    /**
     * A valid ISO alpha-2 country code.
     * Used when an IP address cannot be translated.
     */
    'fallback' => 'BE',

    'repos' => [
        'cookie' => [
            'name' => 'geo', // The cookie's name when set on the users' browsers
        ],
    ],

    /**
     * The valid FQCN of your custom transformer.
     * When set, values retrieved from the repository will be transformed first using this class.
     */
    'transformer' => null,
];

用法

首先，您需要决定要使用哪个服务。

探测器

决定后，将GEO_DETECTORS_DRIVER环境变量设置为其正确值。请参阅配置文件以获取正确的值。

GeoIP2数据库

生成许可证密钥
将GEO_DETECTORS_MAXMIND_DB_LICENSE_KEY环境变量设置为您的许可证密钥

自动更新本地数据库

IP地址范围可能会随着时间的推移而过时。因此，此包还提供方便的更新命令，您可以安排每周运行一次，以保持一切新鲜。

// Console\Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('geo:update')->weekly();
}

仅适用于使用MaxMind的GeoIP2数据库。

GeoIP2精确Web服务

获取account_id & license_key
设置GEO_DETECTORS_MAXMIND_WEB_ACCOUNT_ID & GEO_DETECTORS_MAXMIND_WEB_LICENSE_KEY环境变量

IP 2 国家

这是一个免费服务。您不需要进行任何配置。

注意：强烈建议为此驱动程序启用缓存。

静态

静态驱动程序适用于本地开发和测试期间的使用。您不应在其他任何环境中使用它，因为它总是返回回退值。

检测访问者的地理位置

将DetectGeoLocation（或别名geo）中间件添加到内核的web中间件堆栈中，然后您就可以开始了。如果您的应用程序位于代理/负载均衡器后面，请确保在TrustProxies之后定义DetectGeoLocation。

'web' => [
    // omitted for brevity
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
    \Dive\Geo\Middleware\DetectGeoLocation::class,
],

检索检测到的国家 🗺

有多种方法可以检索检测到的ISO alpha-2国家代码。

外观

use Dive\Geo\Facades\Geo;

Geo::get();

或使用别名

use Geo;

Geo::get();

助手

geo()->get()

依赖注入

use Dive\Geo\Contracts\Repository;

public function __invoke(Repository $geo)
{
    $geo->get();
}

转换检测到的地理位置 🔷

您很可能希望在使用存储库类上的get调用之后将ISO alpha-2国家代码转换为您自己的Eloquent模型或值对象。您可以定义自己的CountryTransformer，该转换器实现Transformer接口并简单地返回所需的对象。

例如。

namespace App\Transformers;

use App\Models\Country;
use Dive\Geo\Contracts\Transformer;

class CountryTransformer implements Transformer
{
    public function transform(string $iso): Country
    {
        return Country::findByIso($iso);
    }
}

定义类后，请确保在配置文件中提供FQCN。

'transformer' => App\Transformers\CountryTransformer::class,

覆盖现有国家 ✍🏼

在任何时候，您都可以覆盖检测到的国家代码。只需调用

geo('TR'); // helper
Geo::put('TR'); // facade
$geo->put('TR'); // injected

清除缓存 🔥

当启用时，转换的地址将在配置文件中定义的一定时间内保留在缓存中。如果要从缓存中清除这些转换，请使用命令

php artisan geo:clear

注意：缓存驱动必须支持标记，否则在运行上述命令时，所有内容都会被清除。

扩展探测器 👣

如果默认驱动无法满足您的需求，您可以使用自己的自定义驱动来扩展 DetectorManager

use Dive\Geo\Facades\Detector;

Detector::extend('ipapi', function () {
    return new IPApiDetector(...);
});

测试 🔎

此软件包提供了 Repository 和 Detector 合约的模拟实现，这样您就可以在单元测试中进行断言，并确保您发布的代码无bug 💪。只需调用其中一个的 fake 方法即可

use Dive\Geo\Facades\Detector;
use Dive\Geo\Facades\Geo;

Detector::fake();
Geo::fake();

测试（软件包）

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志

贡献

有关详细信息，请参阅贡献指南

安全

如果您发现任何安全问题，请通过电子邮件发送到 oss@dive.be 而不是使用问题跟踪器。

致谢

许可证

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

dive-be / laravel-geo

维护者

详细信息