<commit_before># Geographer
[![Build Status](https://travis-ci.org/MenaraSolutions/geographer.svg)](https://travis-ci.org/MenaraSolutions/geographer)
[![Code Climate](https://codeclimate.com/github/MenaraSolutions/geographer/badges/gpa.svg)](https://codeclimate.com/github/MenaraSolutions/geographer/badges)
[![Test Coverage](https://codeclimate.com/github/MenaraSolutions/geographer/badges/coverage.svg)](https://codeclimate.com/github/MenaraSolutions/geographer/badges)
[![Total Downloads](https://poser.pugx.org/menarasolutions/geographer/downloads)](https://packagist.org/packages/menarasolutions/geographer)
[![Latest Stable Version](https://poser.pugx.org/MenaraSolutions/geographer/v/stable.svg)](https://packagist.org/packages/MenaraSolutions/geographer)
[![Latest Unstable Version](https://poser.pugx.org/MenaraSolutions/geographer/v/unstable.svg)](https://packagist.org/packages/MenaraSolutions/geographer)
[![License](https://poser.pugx.org/MenaraSolutions/geographer/license.svg)](https://packagist.org/packages/MenaraSolutions/geographer)

Geographer is a PHP library that knows how any country, state or city is called in any language.

Includes integrations with: Laravel 5, Lumen 5

## Dependencies

* PHP >= 5.6

## Installation via Composer

To install simply run:

```
composer require menarasolutions/geographer
```

Or add it to `composer.json` manually:

```json
{
    "require": {
        "menarasolutions/geographer": "~0.1"
    }
}
```

## Usage

```php
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
$countries = $earth->getCountries();
$thailand = $countries->findOne(['code' => 'TH']);
$thailand->getStates()->toArray();

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

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

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

## Common methods

All objects can do the following:
```php
$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
```

## Earth API

Earth object got the following convenience methods:
```php
$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
```

## Country API

Country objects got the following encapsulated data:
```php
$country->getCode(); // ISO 3611 2 character code
$country->getCode3(); // ISO 3611 3 character code
$country->getGeonamesCode(); // Geonames ID<commit_msg>r Update readme<commit_after># Geographer
[![Build Status](https://travis-ci.org/MenaraSolutions/geographer.svg)](https://travis-ci.org/MenaraSolutions/geographer)
[![Code Climate](https://codeclimate.com/github/MenaraSolutions/geographer/badges/gpa.svg)](https://codeclimate.com/github/MenaraSolutions/geographer/badges)
[![Test Coverage](https://codeclimate.com/github/MenaraSolutions/geographer/badges/coverage.svg)](https://codeclimate.com/github/MenaraSolutions/geographer/badges)
[![Total Downloads](https://poser.pugx.org/menarasolutions/geographer/downloads)](https://packagist.org/packages/menarasolutions/geographer)
[![Latest Stable Version](https://poser.pugx.org/MenaraSolutions/geographer/v/stable.svg)](https://packagist.org/packages/MenaraSolutions/geographer)
[![Latest Unstable Version](https://poser.pugx.org/MenaraSolutions/geographer/v/unstable.svg)](https://packagist.org/packages/MenaraSolutions/geographer)
[![License](https://poser.pugx.org/MenaraSolutions/geographer/license.svg)](https://packagist.org/packages/MenaraSolutions/geographer)

Geographer is a PHP library that knows how any country, state or city is called in any language.

Includes integrations with: Laravel 5, Lumen 5

## Dependencies

* PHP >= 5.6

## Installation via Composer

To install simply run:

```
composer require menarasolutions/geographer
```

Or add it to `composer.json` manually:

```json
{
    "require": {
        "menarasolutions/geographer": "~0.1"
    }
}
```

## Usage

```php
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
$countries = $earth->getCountries();
$thailand = $countries->findOne(['code' => 'TH']);
$thailand->getStates()->toArray();

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

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

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

## Collections

Arrays of administrative divisions (countries, states or cities) are returned as collections – a modern
way of implementing arrays. Some of the available methods are:

```php
$states->sortBy('name'); // States will be sorted by name
$states->setLanguage('ru')->sortBy('name'); // States will be sorted by Russian translations/names
$states->find(['code' => 472039]); // Find 1+ divisions that match specified parameters 
```

## Common methods on division objects

All objects can do the following:
```php
$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
```

## Earth API

Earth object got the following convenience methods:
```php
$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
```

## Country API

Country objects got the following encapsulated data:
```php
$country->getCode(); // ISO 3611 2 character code
$country->getCode3(); // ISO 3611 3 character code
$country->getGeonamesCode(); // Geonames ID
{'fraction_non_alphanumeric': 0.15559201531309816, 'fraction_numerical': 0.005605687722176647, 'mean_word_length': 5.289767841788478, 'pattern_counts': {'":': 4, '<': 3, '<?xml version=': 0, '>': 82, 'https://': 28, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '583145', 'n_tokens_mistral': 2328, 'n_tokens_neox': 2194, 'n_words': 599}