PHPackages                             risetechapps/geonames-for-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. risetechapps/geonames-for-laravel

ActiveLibrary[Utility & Helpers](/categories/utility)

risetechapps/geonames-for-laravel
=================================

Coleção de dados sobre região, países, estados e cidades.

2.0.0(1mo ago)0241↓68.1%MITPHPPHP ^8.3

Since Dec 24Pushed 1mo agoCompare

[ Source](https://github.com/risetechapps/geonames-for-laravel)[ Packagist](https://packagist.org/packages/risetechapps/geonames-for-laravel)[ RSS](/packages/risetechapps-geonames-for-laravel/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (6)Versions (4)Used By (0)

Geonames - RiseTech Apps
========================

[](#geonames---risetech-apps)

O **Geonames** é um pacote Laravel projetado para gerenciar dados geográficos globais (Regiões, Países, Estados e Cidades) com foco em **ultra-performance** e arquitetura multi-tenant.

A arquitetura do pacote utiliza um carregamento em árvore (Tree-loading), segmentando os dados em arquivos JSON específicos por região. Isso garante que apenas o conteúdo geográfico necessário seja carregado na memória, economizando recursos do servidor.

---

📥 Instalação
------------

[](#-instalação)

### 1. Instale o pacote via Composer

[](#1-instale-o-pacote-via-composer)

```
composer require risetechapps/geonames-for-laravel
```

### 2. Execute o instalador

[](#2-execute-o-instalador)

```
php artisan geonames:install
```

Este comando irá:

- ✅ Publicar o arquivo de configuração
- ✅ Perguntar se deseja criar migration para Models
- ✅ **Baixar os dados geográficos** (regiões, países, estados, cidades)

### 3. Ou baixe os dados manualmente

[](#3-ou-baixe-os-dados-manualmente)

Se preferir baixar os dados separadamente:

```
# Baixar todos os países disponíveis (⚠️ consome memória e disco)
php artisan geonames:install-data

# Recomendado: Baixar países específicos (códigos ISO3)
php artisan geonames:install-data --countries=BRA
php artisan geonames:install-data --countries=BRA,USA,ARG,DEU

# Forçar reinstalação (sobrescreve existentes)
php artisan geonames:install-data --force

# Simular sem baixar (ver o que seria baixado)
php artisan geonames:install-data --dry-run
```

> **💡 Dica:** Baixar todos os 250 países consome ~100MB de disco e requer ~512MB de RAM. Para a maioria das aplicações, baixar apenas os países necessários é suficiente.

### Estrutura de Dados Baixados

[](#estrutura-de-dados-baixados)

Após a instalação, os dados são organizados assim:

```
resources/geonames/json/
├── regions.json          # Regiões mundiais
├── countries.json        # Dados dos países
├── BRA/                  # Pasta do Brasil (ISO3)
│   ├── index.json        # Estados do Brasil
│   ├── SP/               # Pasta de São Paulo (ISO2)
│   │   └── index.json    # Cidades de São Paulo
│   ├── RJ/               # Pasta do Rio de Janeiro
│   │   └── index.json    # Cidades do Rio
│   └── ...
├── USA/                  # Pasta dos EUA
│   ├── index.json        # Estados americanos
│   └── ...
└── ...

```

> **Nota:** Os dados são armazenados em `resources/geonames/json/` para evitar conflitos com outros pacotes.

### Configuração (.env)

[](#configuração-env)

```
# URL dos dados (opcional, usa padrão se não definido)
GEONAMES_DATA_URL=https://github.com/risetechapps/geonames-data/releases/latest/download/

# Configurações de cache
GEONAMES_CACHE_TTL=86400
GEONAMES_CACHE_PREFIX=geonames
GEONAMES_DEFAULT_LANGUAGE=pt-BR
```

---

🛠 Estrutura de Pastas
---------------------

[](#-estrutura-de-pastas)

Para que o pacote funcione corretamente, os dados JSON devem seguir esta hierarquia no diretório de recursos: `resources/geonames/json/{COUNTRY_ISO3}/{STATE_ISO2}/index.json`

---

📖 Como Usar
-----------

[](#-como-usar)

### 1. País (Country)

[](#1-país-country)

Instancie um país usando o código ISO2 ou o Nome. A busca é case-insensitive.

```
use RiseTechApps\Geonames\Features\Country;

$country = new Country('BR');

if ($country->exists()) {
    echo $country->getName();           // Brazil
    echo $country->getEmoji();          // 🇧🇷
    echo $country->getPhoneCode();      // 55
    echo $country->getTimezone();       // America/Sao_Paulo
}
```

### 2. Estados de um País (States)

[](#2-estados-de-um-país-states)

Para obter todos os estados de um país, use o método `states()` e depois `all()`:

```
$country = new Country('BR');

// ⚠️ $country->states() retorna um objeto States (repositório)
// Para obter os dados, use ->all()
$states = $country->states()->all();

foreach ($states as $state) {
    echo $state->getName();    // ACRE, ALAGOAS, AMAZONAS...
    echo $state->getIso2();    // AC, AL, AM...
}

// Outros métodos disponíveis
$country->states()->first();              // Primeiro estado
$country->states()->count();              // Total de estados (27)
$country->states()->search('Sao');       // Busca por nome
$country->states()->paginate(20, 1);     // Paginação
```

### 3. Estado Específico (State)

[](#3-estado-específico-state)

Para buscar um estado específico:

```
use RiseTechApps\Geonames\Features\State;

$country = new Country('BR');
$state = $country->state('SP');  // ou new State('SP', $country)

if ($state->exists()) {
    echo $state->getName();    // SÃO PAULO
    echo $state->getIso2();    // SP
}
```

### 4. Cidades (Cities)

[](#4-cidades-cities)

As cidades são carregadas sob demanda através do estado:

```
$country = new Country('BR');
$state = $country->state('SP');

// ⚠️ $state->cities() retorna um objeto Cities (repositório)
// Para obter os dados, use ->all()
$cities = $state->cities()->all();

foreach ($cities as $city) {
    echo $city->getName();       // SÃO PAULO, CAMPINAS...
    echo $city->getLatitude();   // -23.5475
    echo $city->getLongitude();  // -46.6361
}

// Outros métodos disponíveis
$state->cities()->first();                // Primeira cidade
$state->cities()->count();                // Total de cidades
$state->cities()->search('Santo');      // Busca por nome
$state->cities()->paginate(50, 1);      // Paginação
```

### 5. Uso com Helper Global

[](#5-uso-com-helper-global)

```
// Acessar via helper geonames()
$country = geonames()->country('BR');

// Listar todos os países
$countries = geonames()->countries()->all();

// Listar regiões
$regions = geonames()->regioes()->all();
```

---

🧬 API de Métodos
----------------

[](#-api-de-métodos)

### Objeto `Country`

[](#objeto-country)

#### Propriedades

[](#propriedades)

- `getName()`: Retorna o nome internacional.
- `getNative()`: Retorna o nome nativo do país.
- `getIso2()` / `getIso3()`: Retorna os códigos padrão ISO.
- `getPhoneCode()`: Retorna o DDI (ex: 55).
- `getCurrencySymbol()`: Retorna o símbolo da moeda (ex: R$).
- `getEmoji()`: Retorna a bandeira do país em formato Emoji.
- `getTimezone()`: Retorna o fuso horário principal.

#### Relacionamentos

[](#relacionamentos)

- `states()`: Retorna objeto `States` (repositório).
    - **Use** `$country->states()->all()` para obter Collection.
- `state('SP')`: Retorna um `State` específico.

### Objeto `States` (Repositório)

[](#objeto-states-repositório)

- `all()`: Retorna Collection de todos os estados.
- `first()`: Retorna o primeiro estado.
- `count()`: Retorna o total de estados.
- `search('termo')`: Busca por nome parcial.
- `paginate(20, 1)`: Retorna array paginado.
- `find('SP')`: Busca estado por código/nome.

### Objeto `State`

[](#objeto-state)

#### Propriedades

[](#propriedades-1)

- `getName()`: Nome completo do estado.
- `getIso2()`: Sigla/UF (ex: AC, SP, RJ).
- `getCountry()`: Retorna o objeto `Country` pai.

#### Relacionamentos

[](#relacionamentos-1)

- `cities()`: Retorna objeto `Cities` (repositório).
    - **Use** `$state->cities()->all()` para obter Collection.
- `city('São Paulo')`: Retorna uma `City` específica.

### Objeto `Cities` (Repositório)

[](#objeto-cities-repositório)

- `all()`: Retorna Collection de todas as cidades.
- `first()`: Retorna a primeira cidade.
- `count()`: Retorna o total de cidades.
- `search('termo')`: Busca por nome parcial.
- `paginate(50, 1)`: Retorna array paginado.

### Objeto `City`

[](#objeto-city)

- `getName()`: Nome da cidade.
- `getLatitude()` / `getLongitude()`: Coordenadas geográficas.
- `toArray()`: Retorna array com todos os dados.

### Objeto `Geonames` (Helper)

[](#objeto-geonames-helper)

```
$geonames = geonames();
$geonames->countries()->all();    // Todos os países
$geonames->country('BR');          // País específico
$geonames->regioes()->all();      // Todas as regiões
```

---

⚠️ Padrão de Repositório (Lazy Loading)
---------------------------------------

[](#️-padrão-de-repositório-lazy-loading)

O Geonames utiliza um padrão de **repositório** para carregamento lazy de dados:

```
// ❌ Incorreto: Não retorna dados diretamente
$country->states();           // Retorna objeto States
$state->cities();              // Retorna objeto Cities

// ✅ Correto: Chame ->all() para obter os dados
$country->states()->all();     // Retorna Collection de State
$state->cities()->all();       // Retorna Collection de City

// ✅ Também funciona: Busca específica
$country->state('SP');         // Retorna objeto State
$state->city('São Paulo');     // Retorna objeto City
```

**Por quê?** Isso permite carregar dados sob demanda, com cache e paginação eficientes.

---

⚡ Performance e Cache
---------------------

[](#-performance-e-cache)

O Geonames utiliza o driver de cache nativo do Laravel para armazenar os dados processados por 24 horas (86400 segundos). O cache é segmentado por chaves únicas baseadas na hierarquia geográfica (ex: `geonames.cities.BRA.SP`), o que otimiza drasticamente o tempo de resposta e evita I/O de disco desnecessário.

### Comandos Artisan

[](#comandos-artisan)

```
# Instalação completa (baixa dados + publica config)
php artisan geonames:install

# Apenas download de dados
php artisan geonames:install-data --countries=BRA,USA

# Pré-aquecer cache (recomendado em produção)
php artisan geonames:cache-warm --country=BRA

# Limpar cache
php artisan geonames:cache-clear

# Benchmark de performance
php artisan geonames:benchmark
```

> **⚠️ Atenção:** Comandos que processam todos os países (`--all`) consomem ~512MB de RAM. Use `--country=XX` para processar países específicos e economizar memória.

---

🛠️ Requisitos
-------------

[](#️-requisitos)

DependênciaVersão mínimaPHP8.3Laravel12.x---

🧑‍💻 Autor
---------

[](#‍-autor)

**Rise Tech**
📧
🌐
💼

---

🧩 Trait HasGeonames (Para Models)
---------------------------------

[](#-trait-hasgeonames-para-models)

Adicione suporte geográfico a qualquer Model do Laravel.

### Instalação

[](#instalação)

```
// No seu Model
use RiseTechApps\Geonames\Traits\HasGeonames;

class User extends Model
{
    use HasGeonames;
}
```

### Uso Básico

[](#uso-básico)

```
// Definir localização (com validação automática)
$user->setLocation('BR', 'SP', 'São Paulo');
$user->save();

// Acessar objetos
$user->country(); // Retorna Country|null
$user->state();   // Retorna State|null
$user->city();    // Retorna City|null

// Formatar endereço
$user->getFullAddress('short');  // "São Paulo, SP"
$user->getFullAddress('medium'); // "São Paulo, SÃO PAULO, Brazil"
$user->getFullAddress('long');   // "São Paulo, SÃO PAULO, Brazil 🇧🇷 (America/Sao_Paulo)"

// Verificações
$user->hasLocation();         // Tem pelo menos país?
$user->hasCompleteLocation(); // Tem país, estado e cidade?
$user->getTimezone();         // Fuso horário

// Queries
User::whereCountry('BR')->get();
User::whereState('SP')->get();
User::whereRegion('EUROPE')->get();

// Distância entre usuários
$distance = $user1->distanceTo($user2, 'km');
```

### Comando de Instalação

[](#comando-de-instalação)

```
# Instalação completa
php artisan geonames:install

# Com migration para um model específico
php artisan geonames:install --model=User --migration
```

Veja a [documentação completa](docs/has-geonames-examples.md) para mais exemplos.

---

🪪 Licença
---------

[](#-licença)

Distribuído sob a licença MIT. RiseTech Apps © 2025.

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance88

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~63 days

Total

3

Last Release

59d ago

Major Versions

1.1.0 → 2.0.02026-04-28

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/160299136?v=4)[Rise Tech](/maintainers/risetechapps)[@risetechapps](https://github.com/risetechapps)

---

Top Contributors

[![risetechapps](https://avatars.githubusercontent.com/u/160299136?v=4)](https://github.com/risetechapps "risetechapps (12 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/risetechapps-geonames-for-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/risetechapps-geonames-for-laravel/health.svg)](https://phpackages.com/packages/risetechapps-geonames-for-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[illuminate/pipeline

The Illuminate Pipeline package.

9348.3M267](/packages/illuminate-pipeline)[illuminate/pagination

The Illuminate Pagination package.

10533.5M991](/packages/illuminate-pagination)[illuminate/redis

The Illuminate Redis package.

8314.4M362](/packages/illuminate-redis)[illuminate/cookie

The Illuminate Cookie package.

224.5M132](/packages/illuminate-cookie)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)