README

Geographer是一个PHP库，知道任何国家、州或城市在所有语言中的名称。官方网站上的文档

包含以下集成：Laravel 5, Lumen 5

依赖项

PHP >= 5.5

通过Composer安装

安装只需运行

$ composer require menarasolutions/geographer

或手动添加到composer.json

{
    "require": {
        "menarasolutions/geographer": "~0.3"
    }
}

此主包随英文语言版提供，因此请为其他语言添加额外依赖，例如。

$ composer require menarasolutions/geographer-es

用法

use MenaraSolutions\Geographer\Earth;
use MenaraSolutions\Geographer\Country;

// Default entry point is our beautiful planet
$earth = new Earth();

// Give me a list of all countries please
$earth->getCountries()->toArray();

// Oh, but please try to use short versions, eg. USA instead of United States of America
$earth->getCountries()->useShortNames()->toArray();

// Now please give me all states of Thailand
$thailand = $earth->getCountries()->findOne(['code' => 'TH']); // You can call find on collection
$thailand = $earth->findOne(['code' => 'TH']); // Or right away on division
$thailand = $earth->findOneByCode('TH'); // Alternative shorter syntax
$thailand = Country::build('TH'); // You can build a country object directly, too
$thailand->getStates()->toArray();

// Oh, but I want them in Russian
$thailand->getStates()->setLocale('ru')->toArray();

// Oh, but I want them inflicted to 'in' form (eg. 'in Spain')
$thailand->getStates()->setLocale('ru')->inflict('in')->toArray();

// Or if you prefer constants for the sake of IDE auto-complete
$thailand->getStates()->setLocale(TranslationAgency::LANG_RUSSIAN)->inflict(TranslationAgency::FORM_IN)->toArray();

// What's the capital and do you have a geonames ID for that? Or maybe latitude and longitude?
$capital = $thailand->getCapital();
$capital->getGeonamesCode();
$capital->getLatitude();
$capital->getLongitude();

集合

行政区域（国家、州或城市）数组作为集合返回 - 这是实现数组的一种现代方式。一些可用方法包括

$states->sortBy('name'); // States will be sorted by name
$states->setLocale('ru')->sortBy('name'); // States will be sorted by Russian translations/names
$states->find(['code' => 472039]); // Find 1+ divisions that match specified parameters 
$states->findOne(['code' => 472039]); // Return the first match only
$states->findOneByCode(472039); // Convenience magic method
$states->toArray(); // Return a flat array of states
$states->pluck('name'); // Return a flat array of state names

区域对象的常用方法

所有对象都可以执行以下操作

$object->toArray(); // Return a flat array with all data
$object->parent(); // Return a parent (city returns a state, state returns a country)
$object->getCode(); // Get default unique ID
$object->getShortName(); // Get short (colloquial) name of the object
$object->getLongName(); // Get longer name
$object->getCodes(); // Get a plain array of all available unique codes

您可以通过多种方式访问信息，使用您舒适的方式

$object->getName(); // Get object's name (inflicted and shortened when necessary)
$object->name; // Same effect
$object['name']; // Same effect
$object->toArray()['name']; // Same effect again

子区域标准

默认情况下，我们将使用ISO-3166-1国家分类和ISO 3166-2州分类。因此，没有ISO代码的国家或州默认情况下不可见。请注意，FIPS 10-4是一个已废弃（已弃用）的标准。最好不要依赖它 - 新的州和/或国家不会出现在FIPS中。

您可以使用setStandard方法更改子区域标准

$country->setStandard(DefaultManager::STANDARD_ISO); // ISO subdivisions
$country->setStandard(DefaultManager::STANDARD_FIPS); // FIPS 10-4 subdivisions
$country->setStandard(DefaultManager::STANDARD_GEONAMES); // Geonames subdivisions

这将影响getStates()和getCountries()输出。

Earth API

Earth对象有以下便捷方法

$earth->getAfrica(); // Get a collection of African countries
$earth->getEurope(); // Get a collection of European countries
$earth->getNorthAmerica(); // You can guess
$earth->getSouthAmerica(); 
$earth->getAsia();
$earth->getOceania();

$earth->getCountries(); // A collection of all countries
$earth->withoutMicro(); // Only countries that have population of at least 100,000

默认情况下，我们将使用ISO 3166-1国家分类。

国家API

国家对象有以下封装数据

$country->getCode(); //ISO 3166-1 alpha-2 (2 character) code
$country->getCode3(); // ISO 3166-1 alpha-3
$country->getNumericCode(); // ISO 3166-1 numeric code
$country->getGeonamesCode(); // Geonames ID
$country->getFipsCode(); // FIPS code
$country->getArea(); // Area in square kilometers
$country->getCurrencyCode(); // National currency, eg. USD
$country->getPhonePrefix(); // Phone code, eg. 7 for Russia
$country->getPopulation(); // Population
$country->getLanguage(); // Country's first official language

$country->getStates(); // A collection of all states
Country::build('TH'); // Build a country object based on ISO code

Geonames、ISO 3166-1 alpha-2、alpha-3和数字代码是引用国家在数据存储中的四种可行选项。

州API

目前，Geographer仅保留人口超过50,000的城市，以提高性能。

$state->getCode(); // Get default code (currently Geonames)
$state->getIsoCode(); // Get ISO 3166-2 code  
$state->getFipsCode(); // Get FIPS code
$state->getGeonamesCode(); // Get Geonames code

$state->getCities(); // A collection of all cities
$state = State::build($id); // Instantiate a state directly, based on $id provided (Geonames or ISO)

Geonames、ISO 3166-2和FIPS都是唯一的代码，因此都可以用于在数据存储中引用州。

城市API

$city->getCode(); // This is always a Geonames code for now
$city = City::build($id); // Instantiate a city directly, based on $id provided (Geonames) 
$city->getLatitude(); // City's latitude
$city->getLongitude(); // City's longitude
$city->getPopulation(); // Population

Geonames ID是目前唯一可行的方式来在数据存储中引用城市。

框架集成

官方Laravel包

当前覆盖率：子区域

子区域数据保存在单独的仓库中 - geographer-data，以便不同的语言SDK可以重用它。

当前覆盖率：翻译

默认情况下，Geographer假定您使用Packagist（Composer）安装语言包，因此我们将在vendor/文件夹中期待它们。无需手动打开额外的语言，但如果您尝试使用不存在的语言，请 expect an exception。

英文文本包含在数据包中，并用作默认元数据。

愿景

我们的主要原则和目标是

轻量级和独立 - 这样这个包就可以单独拉取到任何地方
覆盖率 - Geographer应该覆盖所有国家和语言
可扩展性 - 开发者应该能够轻松地覆盖和扩展

性能

尽管目前不是首要任务，但我们将尽力保持合理的CPU和内存性能。一些基准测试

基于ID膨胀城市

时间：6 毫秒，内存：81056 字节

视频教程

我刚刚开设了一个教育性的YouTube频道，将涵盖软件开发和DevOps的顶级IT趋势：config.sys

待办事项

添加基本的空间索引
添加一些单元测试（除了现有的集成测试之外）
为语言包添加覆盖率信息

使用Geographer的项目

GrammarCI – 开发者的错别字检测

告诉我们您的信息！

贡献

阅读我们的贡献指南

许可证

MIT许可证（MIT）版权（c）2016 Denis Mysenko

在此特此免费授予任何获得本软件及其相关文档副本（以下简称“软件”）的人，在不受限制的情况下处理软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向软件提供者提供软件的人这样做，前提是遵守以下条件：

menarasolutions / geographer

维护者

详情