PHP code example of marksamp / ibge-localidades

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

marksamp / ibge-localidades example snippets

arksamp\IbgeLocalidades\IbgeClient;

// Criar instância do cliente
$ibge = IbgeClient::create();

// Buscar todos os estados
$estados = $ibge->estados()->todos();

// Buscar estado por sigla
$sp = $ibge->estados()->porSigla('SP');

// Buscar municípios de um estado
$municipiosSP = $ibge->municipios()->porEstado('SP');

// Buscar todos os estados (ordem alfabética por padrão)
$estados = $ibge->estados()->todos();

// Buscar estado por ID
$estado = $ibge->estados()->porId(35);

// Buscar estado por sigla
$estado = $ibge->estados()->porSigla('SP');

// Buscar estados por região (ordem alfabética)
$estados = $ibge->estados()->porRegiao(3); // Sudeste

// Ordenações alternativas
$estados = $ibge->estados()->todosOrdemOriginal(); // Ordem da API
$estados = $ibge->estados()->todosPorId();         // Por ID crescente

$sp = $ibge->estados()->porSigla('SP');

echo $sp->nome;           // "São Paulo"
echo $sp->sigla;          // "SP"
echo $sp->id;             // 35
echo $sp->regiao->nome;   // "Sudeste"
echo $sp->regiao->sigla;  // "SE"

// Converter para array
$dados = $sp->toArray();

// Buscar todos os municípios (ordem alfabética - cuidado: são muitos!)
$municipios = $ibge->municipios()->todos();

// Buscar município por ID
$municipio = $ibge->municipios()->porId(3550308);

// Buscar municípios por estado (ordem alfabética)
$municipios = $ibge->municipios()->porEstado('SP');
$municipios = $ibge->municipios()->porEstado(35);

// Buscar municípios por microrregião (ordem alfabética)
$municipios = $ibge->municipios()->porMicrorregiao(11);

// Buscar municípios por mesorregião (ordem alfabética)
$municipios = $ibge->municipios()->porMesorregiao(15);

// Buscar municípios por nome (ordem alfabética)
$municipios = $ibge->municipios()->buscarPorNome('Santos');

// Ordenações alternativas
$municipios = $ibge->municipios()->todosOrdemOriginal(); // Ordem da API
$municipios = $ibge->municipios()->todosPorId();         // Por ID crescente

$saoPaulo = $ibge->municipios()->porId(3550308);

echo $saoPaulo->nome; // "São Paulo"
echo $saoPaulo->id;   // 3550308

if ($saoPaulo->microrregiao) {
    echo $saoPaulo->microrregiao->nome;
    
    if ($saoPaulo->microrregiao->mesorregiao) {
        echo $saoPaulo->microrregiao->mesorregiao->nome;
        echo $saoPaulo->microrregiao->mesorregiao->estado->nome;
    }
}

use Marksamp\IbgeLocalidades\Exceptions\IbgeLocalidadesException; // Exception base
use Marksamp\IbgeLocalidades\Exceptions\IbgeApiException;          // Erros da API
use Marksamp\IbgeLocalidades\Exceptions\HttpException;             // Erros HTTP

try {
    $estado = $ibge->estados()->porSigla('XX');
} catch (IbgeApiException $e) {
    echo "Erro na API do IBGE: " . $e->getMessage();
} catch (HttpException $e) {
    echo "Erro HTTP: " . $e->getMessage();
} catch (IbgeLocalidadesException $e) {
    echo "Erro geral da biblioteca: " . $e->getMessage();
}

class Estado {
    public readonly int $id;
    public readonly string $sigla;
    public readonly string $nome;
    public readonly Regiao $regiao;
}

class Municipio {
    public readonly int $id;
    public readonly string $nome;
    public readonly ?Microrregiao $microrregiao;
    public readonly ?string $regiaoImediata;
}

class Regiao {
    public readonly int $id;
    public readonly string $sigla;
    public readonly string $nome;
}

use Marksamp\IbgeLocalidades\Http\HttpClientInterface;

class MeuHttpClient implements HttpClientInterface 
{
    public function get(string $url, array $headers = []): array
    {
        // Sua implementação personalizada
    }
}

$ibge = new IbgeClient(new MeuHttpClient());

$estados = $ibge->estados()->todos(); // A-Z por nome
$municipios = $ibge->municipios()->porEstado('SP'); // A-Z por nome

// Estados
$estados = $ibge->estados()->todosOrdemOriginal(); // Ordem da API do IBGE
$estados = $ibge->estados()->todosPorId();         // Por ID (1, 11, 12...)

// Municípios  
$municipios = $ibge->municipios()->todosOrdemOriginal(); // Ordem da API
$municipios = $ibge->municipios()->todosPorId();         // Por ID crescente

class CepService extends BaseService 
{
    public function buscar(string $cep): Endereco
    {
        $data = $this->makeRequest("/localidades/cep/{$cep}");
        return Endereco::fromArray($data);
    }
}

// Buscar todos os municípios de SP e filtrar por nome
$municipiosSP = $ibge->municipios()->porEstado('SP');

// Filtrar municípios que começam com 'São'
$municipiosSao = array_filter($municipiosSP, function($municipio) {
    return str_starts_with($municipio->nome, 'São');
});

// Ordenar por nome
usort($municipiosSao, fn($a, $b) => $a->nome <=> $b->nome);

class CachedIbgeClient 
{
    private array $cache = [];
    
    public function __construct(private IbgeClient $client) {}
    
    public function getEstados(): array 
    {
        if (!isset($this->cache['estados'])) {
            $this->cache['estados'] = $this->client->estados()->todos();
        }
        
        return $this->cache['estados'];
    }
}