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()的输出。

地球API

地球对象有以下便利方法

$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/文件夹中期待它们。无需手动开启额外的语言，但如果尝试使用不存在的语言，请期待异常。

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

愿景

我们的主要原则和目标是

1. 轻量级且独立——这样这个包就可以独立拉取到任何地方
2. 覆盖范围——Geographer应该涵盖所有国家和语言
3. 可扩展——开发者应该能够轻松地重写和扩展

性能

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

根据城市ID进行膨胀

时间：6 ms，内存：81056 字节

视频教程

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

待办事项

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

使用Geographer的项目

• GrammarCI – 为开发者提供的错别字检测

告诉我们你的！

贡献

阅读我们的贡献指南

许可证

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

在此，任何人免费获得本软件及其相关文档副本（以下简称“软件”），可以无限制地使用、复制、修改、合并、发布、分发、再许可或出售软件副本，并允许向软件提供者提供软件的人这样做，前提是遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

软件按“原样”提供，不提供任何形式的保证，无论是明示的、暗示的，包括但不限于适销性、特定用途适用性和非侵权性保证。在任何情况下，作者或版权持有人不对任何索赔、损害或其他责任承担责任，无论该责任是基于合同、侵权或其他方式，源于、源于或与软件或其使用或其他交易有关。