README

由 igaster/laravel_cities 分支而来

简介

本地部署和使用 geonames.org（例如 MaxCDN）数据库以查询国家/城市
包含纬度和经度
针对搜索和遍历树结构优化的嵌套集合模型。
提供了一个 Eloquent 模型（geo），具有多个查询范围，以帮助您构建查询。
提供了一个简单的 API，您可以使用它来创建 AJAX 调用。（例如，在键入时搜索等）。
一个可插入到您表单中的样本 vue.js 组件，它提供了一个 UI 来选择位置

您得不到的

geoIP 和邮政编码（免费集中不包含）
小于“第3级行政区”的地图元素（=城市）

说明

使用 Composer 安装。运行

composer require awkwardideas/laravel_cities

在 app.php 中添加服务提供者

'providers' => [
    //...
    AwkwardIdeas\LaravelCities\GeoServiceProvider::class,
];

在应用程序存储文件夹（'\storage\geo'）中创建一个名为 geo 的文件夹。从 geonames.org（http://download.geonames.org/export/dump）下载并解压 "hieararcy.txt" 和 "allCountries.txt"。

提示：使用以下命令在远程服务器上快速下载

mkdir storage/geo
cd storage/geo
wget http://download.geonames.org/export/dump/allCountries.zip && unzip allCountries.zip && rm allCountries.zip
wget http://download.geonames.org/export/dump/hierarchy.zip && unzip hierarchy.zip && rm hierarchy.zip

迁移和种植。运行

php artisan migrate
php artisan geo:seed

注意：如果您不想安装所有国家，您可以仅下载特定国家的文件（例如 US.txt），然后使用以下命令导入每个文件

php artisan geo:seed US --append

使用自定义数据种植

在 storage\geo 中创建一个包含自定义数据的 json 文件，并运行以下命令来选择要种植的文件

php artisan geo:json

如果项目在数据库中存在（根据 'id' 值），则将其更新，否则插入新条目。例如，以下 json 文件将重命名 United States 为 USA，并将添加一个子项目（由 parent_id 值设置）

[
  {
    "id": 6252001,
    "name": "USA"
  },
  {
    "name": "USA Child Item",
    "parent_id": 6252001,
    "lat": "39.760000",
    "long": "-98.500000"
  }
]

请注意，向数据库添加新项目将重新索引所有项目以重建树结构。请耐心等待...

提供了一个示例文件： countryNames.json，该文件更新了官方国家名称，并带有最受欢迎的简写版本。

提示：您可以通过查询 API 获取 DB 的 json 表示形式（见下文）

地理模型

您可以使用 AwkwardIdeas\LaravelCities\Geo 模型来访问数据库。以下是可以用的属性列表

$geo->name;       // name of geographical point in plain ascii
$geo->country;    // 2-letter country code (ISO-3166)
$geo->id;         // Original id from geonames.org database (geonameid)
$geo->lat;        // latitude in decimal degrees (wgs84)
$geo->long;       // longitude in decimal degrees (wgs84)
$geo->level;      // Administrator level code (feature code)
// parent_id, left, right, depth: Used to build hierarcy tree

访问 http://www.geonames.org > 信息，获取更详细的描述。

用法

搜索

use AwkwardIdeas\LaravelCities\Geo;

Geo::getCountries();               // Get a Collection of all countries
Geo::getCountry('US');             // Get item by Country code
Geo::findName('Nomos Kerkyras');   // Find item by (ascii) name
Geo::searchNames('york');          // Search item by all alternative names. Case insensitive 
Geo::searchNames('vegas', Geo::getCountry('US'));  // ... and belongs to an item
Geo::getByIds([390903,3175395]);   // Get a Collection of items by Ids

遍历树

$children    = $geo->getChildren();    // Get direct Children of $geo (Collection)
$parent      = $geo->getParent();      // Get single Parent of $geo (Geo)
$ancenstors  = $geo->getAncensors();   // Get Ancenstors tree of $geo from top->bottom (Collection)
$descendants = $geo->getDescendants(); // Get all Descentants of $geo alphabetic (Collection)

检查层次关系

$geo1->isParentOf($geo2);       // (Bool) Check if $geo2 is direct Parent of $geo1
$geo2->isChildOf($geo1);        // (Bool) Check if $geo2 is direct Child of $geo1
$geo1->isAncenstorOf($geo2);    // (Bool) Check if $geo2 is Ancenstor of $geo1
$geo2->isDescendantOf($geo1);   // (Bool) Check if $geo2 is Descentant of $geo1

查询范围（使用它们来构建自定义查询）

Geo::level($level);     // Filter by Administration level: 
                        // Geo::LEVEL_COUNTRY, Geo::LEVEL_CAPITAL, Geo::LEVEL_1, Geo::LEVEL_2, Geo::LEVEL_3
Geo::country('US');     // (Shortcut) Items that belongs to country US 
Geo::capital();         // (Shortcut) Items that are capitals
Geo::search($name);     // Items that conain $name in name OR alternames (Case InSensitive)
Geo::areDescentants($geo);   // Items that belong to $geo

$geo->ancenstors();     // Items that contain $geo
$geo->descendants();    // Items that belong to $geo
$geo->children();       // Items that are direct children of $geo


//--Scope usage Examples:

// Get the States of USA in aplhabetic order
Geo::getCountry('US')
	->children()
	->orderBy('name')
	->get();

// Get the 3 biggest cities of Greece
Geo::getCountry('GR')
	->level(Geo::LEVEL_3)
	->orderBy('population','DESC')
	->limit(3)
	->get();

如果您需要更多功能，可以扩展 AwkwardIdeas\LaravelCities\Geo 模型并添加您的方法。

HTTP API

此包定义了一些 API 路由，您可以通过简单的 HTTP 请求查询数据库。要在其中使用它们，请将其插入到您的路由文件中

\AwkwardIdeas\LaravelCities\Geo::ApiRoutes();

例如，如果您将其插入到 routes\api.php（推荐），则以下 URL 将被注册

响应始终是 Geo 类或集合的 JSON 表示形式。

为了减少带宽，除了 alternames、left、right 和 depth 之外的所有 Geo 模型属性都将返回。您可以通过在任何请求中传递可选参数来更改此行为

Vue 组件

本包附带一个Vue组件，该组件可以连接到提供的API，并通过一系列步骤以交互式方式选择位置。抱歉，目前还没有实时演示，只有一些截图。

步骤 1：选择您的位置。下拉列表异步加载

步骤 2：到达目的地。显示路径和编辑选择按钮

步骤 3：在表单提交时，会提交多个字段

使用指南

假设您正在使用Webpack编译您的资源，并且已包含vue-app.js

添加到您的应用程序

在您的main vue-app.js文件中添加组件声明

Vue.component('geo-select', require('相对路径/to/vendor/awkwardideas/laravel_cities/src/vue/geo-select.vue'));

作为替代，您可以使用以下命令发布组件

artisan vendor:publish --provider="AwkwardIdeas\LaravelCities\GeoServiceProvider"

组件将被导出到/resources/LaravelCities/geo-select.vue，以便您可以进行修改...

如果您选择导出组件，请确保您在vue-app.js文件中注册它

Vue.component('geo-select', require('相对路径/to/resources/LaravelCities/geo-select.vue'));

编译组件

运行npm run dev（或npm run production）

在blade文件中使用

示例

<form action="post-url" method="POST">
	<geo-select></geo-select>
	<!-- Add more form fields here... -->
	<input type="submit">
</form>

以下输入将被提交

geo-id
geo-name
geo-long
geo-lat
geo-country
geo-country-code

完整语法

<geo-select
	prefix = "geo"                    <!-- change the  fields name prefix --> 
	api-root-url = "\api"             <!-- Root url for API -->
	:countries = "[390903,3175395]"   <!-- Limit to specific countries (defined by ids) -->
	:enable-breadcrumb = "true"       <!-- Enable/Disable Breadcrumb -->
></geo-select>

awkwardideas / laravel_cities

维护者

详情