README

GeoMate 是地理定位方面不可或缺的好帮手。IP 地理定位查询、自动重定向（基于国家、大陆、语言等）、站点切换……你想要的它都能做到。

要求

此插件需要 Craft CMS 5.0.0-beta.2 或更高版本。该插件还需要 zlib PHP 扩展。

重要更新

截至 2019 年 12 月 30 日，由于符合 GDPR 和 CCPA 规定，GeoLite2 数据库不再公开提供。之前，这些数据库的公共 URL 已设置为 GeoMate 配置的默认值。自 GeoMate 1.1.0 版本起，这些 URL 已被删除，现在您需要注册一个 Maxmind 账户，获取许可证密钥，并自行配置下载 URL。有关如何进行此操作的更多信息，请参阅下面的 "下载地理定位数据库"。

与之前一样，您也可以手动下载数据库并将其放入您的 dbPath。

安装

要安装此插件，您可以从插件商店安装，或者按照以下说明操作

通过在项目目录中执行 composer require vaersaagod/geomate 使用 composer 安装。
在 Craft 控制面板的设置→插件下安装插件，或从命令行通过 ./craft install/plugin geomate 安装。
为了让 GeoMate 做任何事情，您需要配置它，并且下载地理定位数据库。

GeoMate 概述

GeoMate 帮助您检测访问者的位置和语言偏好，并允许您设置细粒度的规则，以便将用户重定向到正确的站点，或在模板中显示特定位置/语言的特定信息。

GeoMate 依赖于自托管的 Maxmind GeoIP2 数据库进行地理定位，无需外部服务即可查找 IP 信息。默认情况下，GeoMate 使用免费的 Maxmind GeoLite2 数据库，但可以轻松配置为使用商业版本的数据库，只要它是以 MaxMind DB 文件格式。

下载地理定位数据库

为了让 GeoMate 能够获取有关 IP 地址的信息，您需要下载一个 GeoIP2 数据库。获取一个数据库的最简单方法就是使用 Maxmind 的免费 GeoLite2 数据库。为了获得更好的结果和更频繁的更新，您应考虑他们的商业替代方案。

要获取 GeoLite2 数据库，您首先需要在 Maxmind 网站注册一个账户。一旦您有权访问用户控制面板，您需要创建一个许可证密钥。最后，您可以通过访问直接下载页面获取下载 URL，并通过设置相应的 countryDbDownloadUrl 和 cityDbDownloadUrl 配置设置让 GeoMate 知道它们。在撰写本文时，URL 应该是（用您的许可证密钥替换 YOUR_LICENSE_KEY）

'countryDbDownloadUrl' => 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=YOUR_LICENSE_KEY&suffix=tar.gz',
'cityDbDownloadUrl' => 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=YOUR_LICENSE_KEY&suffix=tar.gz',

请注意，尽管这是推荐的方法，您也可以手动下载文件，或者通过其他机制，并将它们放入 dbPath 中。

GeoMate 随附一个方便的实用程序，可以帮助您下载数据库。您可以通过控制面板主菜单中的“工具”>“GeoMate”访问它。请检查设置是否如所需，然后通过单击“立即更新”按钮下载数据库。

您还可以通过直接访问 geomate/database/update-database 控制器操作来下载数据库，或者设置一个定时任务在固定时间间隔调用它。您的安装的动作 URL 在实用程序中显示。

使用 GeoMate

您可以通过 craft.geomate.country、craft.geomate.countryCode 和 craft.geomate.city 模板变量获取用户位置信息。

通过配置 redirectMap 配置设置，您可以定义每个站点所需的地理位置或语言信息规则。如果您想自动将用户重定向到适当的站点，可以启用 autoRedirectEnabled 配置设置，或者您可以使用 craft.geomate.redirectInformation 模板变量在模板中获取信息，并显示横幅或弹出窗口来触发用户切换站点。

GeoMate 还提供了一个助手来构建站点切换器，即 craft.geomate.getSiteLinks 模板变量，以及一些 twig 函数，addOverrideParam 和 addRedirectParam，以确保 GeoMate 捕获到用户已选择特定站点所需的参数。

有相当多的配置设置可以用来调整内容，所以请确保您阅读它们以了解默认设置，以及如何根据您的需求使用它们。

在本地工作期间，您需要通过使用 GeoMate 的 forceIp 配置设置来覆盖 IP 以使其发挥作用（因为如果您不这样做，它将尝试查找 127.0.0.1，而这不会返回任何结果）。

配置

您可以通过在 Craft 配置文件夹中创建一个名为 geomate.php 的文件来配置 GeoMate，并按需覆盖设置。

cacheEnabled [布尔值]

默认值: true
启用或禁用 IP 数据的缓存。

cacheDuration [字符串|整数]

默认值: 'P7D'
查找 IP 数据应缓存的持续时间，设置为日期间隔字符串或表示秒数的整数。

useSeparateLogfile [布尔值]

默认值: true
当启用时，GeoMate 将在 Craft 的日志路径中创建并使用自己的日志文件，名为 geomate.log。

logLevel [整数]

默认值: \yii\log\Logger::LEVEL_ERROR
当使用 GeoMate 的日志文件（即 useSeparateLogfile 设置为 true）时，您可以指定应该记录哪些日志级别。默认情况下，只会记录错误，但如果将其设置为 \yii\log\Logger::LEVEL_WARNING 或 \yii\log\Logger::LEVEL_INFO，您将获得更多信息。

dbPath [字符串]

默认值: ''
GeoIP 数据库的路径。如果没有给出（默认），数据库将存储在 /storage/geomate 或 Craft 的存储路径中定义的任何路径。

countryDbFilename [字符串]

默认值: 'GeoLite2-Country.mmdb'
GeoIP country 数据库的文件名。

cityDbFilename [字符串]

默认值: 'GeoLite2-City.mmdb'
GeoIP city 数据库的文件名。

countryDbDownloadUrl [字符串|null]

默认值: null
GeoIP country 数据库的下载 URL。

cityDbDownloadUrl [字符串|null]

默认值: null
GeoIP city 数据库的下载 URL。

downloadDbIfMissing [布尔值]

默认值: false
如果 GeoMate 在尝试进行 IP 查找时找不到指定的数据库，则它将静默失败，记录错误，并且不会进行重定向或返回任何重定向信息。如果您启用此设置，GeoMate 将尝试下载和解压数据库，如果它缺失。

在使用此功能前，请确保下载功能正常工作。如果在下载过程中出现错误，GeoMate将会在每次请求时继续尝试，这可能会消耗大量资源，具体取决于失败的部分。

autoRedirectEnabled [布尔值]

默认值: false
将此设置为true以启用基于redirectMap配置设置的自动重定向用户到网站。

autoRedirectExclude [数组]

默认值：[]
应排除自动重定向的网站处理列表。

redirectMap [数组]

默认值：[]
此强大的配置设置允许您根据检测到的有关位置或语言的信息创建详细的用户重定向规则。

使用此设置的最简单方法是映射网站处理到国家代码。

'redirectMap' => [
    'norwegian' => 'no',
    'swedish' => 'se',
    'global' => '*' 
]

在此示例中，有三个网站，处理程序为norwegian、swedish和global。来自挪威的访客将被重定向到norwegian网站，来自瑞典的访客将被重定向到swedish网站，其余访客将被发送到global网站。

默认情况下，假定值是检测到的国家代码。但如果将redirectMapSimpleModeKey设置为language，则将使用用户的浏览器语言。

但，您也可以使用更复杂的规则。

'redirectMap' => [
    'norwegian' => [
        'country' => 'no',
    ],
    'eu' => [
        'continent' => 'eu',
        'isInEuropeanUnion' => true
    ],
    'europe' => [
        'continent' => 'eu',
    ],
    'us' => [
        'country' => 'us'
    ],    
    'global' => '*' 
]

规则从上到下解析，并使用第一个匹配项。因此，在上面的示例中交换eu和europe的顺序将使所有来自欧洲的访客都转到处理程序为europe的网站。

如果您没有添加具有通配符规则（例如'global' => '*'）的网站，如果其他规则没有匹配，访客将不会被从着陆的网站重定向。

您也可以在设置规则时使用检测到的浏览器语言。

'redirectMap' => [
    'norsk' => [
        'language' => 'no',
    ],
    'us' => [ // matches 'en-US'
        'language' => 'en',
        'languageRegion' => 'us',
    ],
    'canada' => [ // matches 'en-CA'
        'language' => 'en',
        'languageRegion' => 'ca',
    ],
    'english' => [ // matches all english language codes, 'en', 'en-US', 'en-NZ', etc.
        'language' => 'en',
    ],
]

您甚至可以使用地理位置和语言信息的组合，尽管这可能会变得有点...边缘情况。

/*
 * We have this very special site that we only want to redirect
 * people to if they're located in Norway, but have a browser
 * with jamaican english as their preferred language (yeah, our 
 * site is all about norwegian reggea and jerk chicken).
 */
'redirectMap' => [   
    'special' => [
        'country' => 'no',
        'language' => 'en',
        'languageRegion' => 'jm'
    ],
    'normal' => '*' 
]

重定向映射中的值也可以是数组。

'redirectMap' => [
    'scandinavia' => [
        'country' => ['no', 'se', 'dk', 'fi'],
    ],
    'europe' => [
        'continent' => 'eu',
    ],
    'global' => '*' 
]

请注意，此设置不仅在autoRedirectEnabled设置为true时使用，而且在您使用craft.geomate.redirectInformation时也会使用。

redirectMatchingElementOnly [布尔值]

默认值: false
当设置为true时，基于redirectMap的匹配仅会在请求具有匹配元素且该元素在匹配的网站上可用时发生。当设置为false时，如果找不到匹配的元素，用户将被重定向到匹配的网站的根目录。

redirectMapSimpleModeKey [字符串]

默认值：'country'
当使用redirectMap的简单语法时，默认假定值是国家代码。当设置为'language'时，它将匹配受接受的语言。

redirectIgnoreBots [布尔值]

默认值: true
默认情况下，机器人不会被重定向。禁用此选项以重定向机器人（可能会影响SEO，请小心）。

redirectIgnoreAdmins [布尔值]

默认值: true
默认情况下，管理员不会被重定向。禁用此选项以重定向管理员用户。

redirectIgnoreUserGroups [数组]

默认值：[]
应排除重定向的用户组数组。示例

'redirectIgnoreUserGroups' => ['editors', 'subscribers'],

redirectIgnoreUrlPatterns [数组]

默认值：[]
应排除重定向的URL模式数组。模式可以使用正则表达式，匹配请求的完整路径。为了进行精确匹配，您可以将模式前缀为=。

示例

'redirectIgnoreUrlPatterns' => [
     // Matches '/robots.txt' directly
    '=/robots.txt', 

     // Matches anything that starts with '/dont-redirect/'
    '/^\/dont-redirect\//',

     //Matches a range of sitemap urls like '/sitemap.xml', '/no/sitemap.xml', '/sitemap_portfolio_1.xml', etc.
    '/^\/(no\/|en\/)*sitemap([\s\S])*\.xml$/',
],

redirectOverrideCookieName [字符串]

默认值：'GeoMateRedirectOverride'
注册用户是否已覆盖首选网站（例如通过网站切换器）的cookie名称。

cookieDuration [整数]

默认值：43200
cookie的有效期。

addGetParameterOnRedirect [布尔值]

默认值: false
默认情况下，当用户被重定向时，会设置一个会话（闪存）变量，GeoMate会检测到用户是否被重定向。在某些情况下，这并不是最佳选择，例如，如果网站通过前端缓存（Cloudflare、Varnish或类似服务）提供，并且您想通知用户被重定向。启用此参数后，将查询字符串附加到URL上。

redirectOverrideParam [字符串]

默认值：'__geom'
当用户覆盖网站重定向时，添加到URL的查询字符串参数的名称。

redirectedParam [字符串]

默认值：'__redir'
当用户被重定向（且addGetParameterOnRedirect为true）时，添加到URL的查询字符串参数的名称。

paramValue [字符串]

默认值：'✪'
GeoMate添加到查询字符串参数的值。

forceIp [null|string]

默认值: null
强制使用IP进行地理位置查找。在本地环境中，需要设置一个有效的IP地址才能使GeoMate工作，因为您的本地IP不会返回任何结果。也可以用于调试来自不同位置的IP。

fallbackIp [null|string]

默认值: null
您可以提供一个后备IP，如果提供的IP找不到，将使用该后备IP。可能最好不要使用它，而是在模板中实现一些默认功能。

minimumAcceptLanguageQuality [int]

默认值：80
浏览器提供的Accept-Language头部可能包含任意数量的语言，所有这些语言都有一个质量参数（在这种情况下，范围是0到100），表示用户对这些语言有多熟练。此参数表示语言需要达到什么质量级别，GeoMate才将其视为有效语言。

模板变量

craft.geomate.country([ip=null])

以\GeoIp2\Model\Country模型的形式返回国家信息。如果没有找到信息，则返回null。

默认情况下将使用当前请求的IP地址，但您也可以使用可选的ip参数根据特定IP获取信息。

craft.geomate.countryCode([ip=null])

返回两位字符的国家代码作为string。如果没有找到信息，则返回null。

默认情况下将使用当前请求的IP地址，但您也可以使用可选的ip参数根据特定IP获取信息。

craft.geomate.city([ip=null])

以\GeoIp2\Model\City模型的形式返回国家信息。如果没有找到信息，则返回null。

默认情况下将使用当前请求的IP地址，但您也可以使用可选的ip参数根据特定IP获取信息。

craft.geomate.redirectInformation([ip=null])

根据您的重定向配置返回重定向信息，作为RedirectInfo模型。这些信息可用于向用户显示有关您认为他们应该访问哪个网站的信息，并允许他们根据需要切换。示例

{% set redirectInfo = craft.geomate.redirectInformation() %}

{% if redirectInfo %}
    <div class="popup">
        <p>
            You are currently visiting our {{ currentSite.name }} site. 
            <a href="{{ redirectInfo.url | addOverrideParam }}">Click here</a> to go to our {{ redirectInfo.site.name }} site.
        </p>
    </div>
{% endif %}

默认情况下将使用当前请求的IP地址，但您也可以使用可选的ip参数根据特定IP获取信息。

craft.geomate.isCrawler()

如果当前请求来自爬虫，则返回true。

craft.geomate.isRedirected()

如果当前请求被重定向，则返回true。

craft.geomate.isOverridden()

如果用户已覆盖首选网站，则返回true。

craft.geomate.getSiteLinks()

返回一个包含网站和每个网站的跳转URL的对象数组。对于构建网站切换器等非常有用。

{% set siteLinks = craft.geomate.getSiteLinks() %}
<nav>
    <ul>
        {% for siteLink in siteLinks %}
            <li><a href="{{ siteLink.url | addOverrideParam }}">{{ siteLink.site.name }}</a></li>
        {% endfor %}
    </ul>
</nav>

craft.geomate.getLanguages()

返回一个包含用户首选浏览器语言的AcceptedLanguage模型数组。

{% set languages = craft.geomate.getLanguages() %}
{% for language in languages %}
    <p>
        Quality: {{ language.quality }}<br>
        Language: {{ language.language }}<br>
        Region: {{ language.region }}<br>
        Script: {{ language.script }}
    </p>
{% endfor %}

Twig过滤器

addOverrideParam

将覆盖参数和值添加到URL。您应该在链接网站时始终添加此参数，例如在网站切换器中。

addRedirectParam

将重定向参数和值添加到URL。实际上并不太有用，但它是存在的。 :)

价格、许可和支持

本插件采用MIT许可协议发布，这意味着您可以随意使用它，只要不将责任归咎于我们。它是免费的，这意味着没有任何支持包含在内，但您仍然可能会获得支持。如果您有任何问题，只需在GitHub上发帖，我们将看看我们能做些什么。

变更日志

请参阅CHANGELOG.MD。

致谢

由Værsågod提供。

本产品包含由MaxMind创建的GeoLite2数据，可在http://www.maxmind.com获取。

图标由Freepik from Flaticon设计。

vaersaagod / geomate

维护者

详细信息

README

要求

重要更新

安装

GeoMate 概述

下载地理定位数据库

使用 GeoMate

配置

cacheEnabled [布尔值]

cacheDuration [字符串|整数]

useSeparateLogfile [布尔值]

logLevel [整数]

dbPath [字符串]

countryDbFilename [字符串]

cityDbFilename [字符串]

countryDbDownloadUrl [字符串|null]

cityDbDownloadUrl [字符串|null]

downloadDbIfMissing [布尔值]

autoRedirectEnabled [布尔值]

autoRedirectExclude [数组]

redirectMap [数组]

redirectMatchingElementOnly [布尔值]

redirectMapSimpleModeKey [字符串]

redirectIgnoreBots [布尔值]

redirectIgnoreAdmins [布尔值]

redirectIgnoreUserGroups [数组]

redirectIgnoreUrlPatterns [数组]

redirectOverrideCookieName [字符串]

cookieDuration [整数]

addGetParameterOnRedirect [布尔值]

redirectOverrideParam [字符串]

redirectedParam [字符串]

paramValue [字符串]

forceIp [null|string]

fallbackIp [null|string]

minimumAcceptLanguageQuality [int]

模板变量

craft.geomate.country([ip=null])

craft.geomate.countryCode([ip=null])

craft.geomate.city([ip=null])

craft.geomate.redirectInformation([ip=null])

craft.geomate.isCrawler()

craft.geomate.isRedirected()

craft.geomate.isOverridden()

craft.geomate.getSiteLinks()

craft.geomate.getLanguages()

Twig过滤器

addOverrideParam

addRedirectParam

价格、许可和支持

变更日志

致谢