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包

当前覆盖率：细分

细分数据保存在单独的repo中 - geographer-data，以便它可以由不同的语言SDK重用。

当前覆盖率：翻译

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

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

愿景

我们的主要原则和目标是

轻量级且独立——这样这个包就可以独立拉取
覆盖率——Geographer应该涵盖所有国家和语言
可扩展性——开发人员应该能够轻松覆盖和扩展

性能

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

根据ID膨胀城市

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

视频教程

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

待办事项

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

使用Geographer的项目

GrammarCI – 开发者的错别字检测

告诉我们您的！

贡献

阅读我们的贡献指南

许可

在此特此授予任何获得本软件及其相关文档副本（以下简称“软件”）的人免费权利，以不受限制地处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本，并允许获得软件的人进行上述操作，但受以下条件约束：

izisoft / geographer

维护者

详细信息