PHPackages                             mugomes/mgcep - 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. mugomes/mgcep

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

mugomes/mgcep
=============

É uma biblioteca leve e simples em PHP para consulta de CEP utilizando a API pública do ViaCEP.

v1.0.0(2mo ago)21LGPL-2.1-onlyPHP

Since Apr 27Pushed 1mo agoCompare

[ Source](https://github.com/bluiceoficial/mgcep)[ Packagist](https://packagist.org/packages/mugomes/mgcep)[ RSS](/packages/mugomes-mgcep/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)DependenciesVersions (2)Used By (0)

MGCEP
=====

[](#mgcep)

Note

This repository has been migrated to Codeberg, please see:

É uma biblioteca **leve e simples em PHP** para consulta de CEP utilizando a API pública do **ViaCEP**, com suporte a **cache local em arquivos** para melhorar desempenho e reduzir requisições externas.

Ideal para aplicações que precisam de **consultas rápidas de endereço**, com **baixo consumo de recursos** e **fácil integração**.

---

✨ Características
-----------------

[](#-características)

- Consulta de CEP via **ViaCEP**
- Cache local em arquivos (`.json`)
- Configuração de tempo de cache (TTL)
- API simples e direta
- Zero dependências externas
- Compatível com **PHP 8+**

---

📦 Instalação
------------

[](#-instalação)

### Manual

[](#manual)

Copie a classe `MGCEP.php` para seu projeto e utilize via `require` ou autoload:

```
composer require mugomes/mgcep;
```

---

⚙️ Configuração
---------------

[](#️-configuração)

Antes de utilizar, é recomendado configurar o diretório de cache:

```
use MGCEP\MGCEP;

$cep = new MGCEP();
$cep->setCacheDir(__DIR__ . '/cache');
```

---

📮 Consulta de CEP
-----------------

[](#-consulta-de-cep)

```
$erro = $cep->getCEP('01001000');

if ($erro) {
    echo $erro;
} else {
    echo $cep->getLogradouro();
}
```

---

🧠 Métodos Públicos
------------------

[](#-métodos-públicos)

### 📁 setCacheDir

[](#-setcachedir)

Define o diretório onde os arquivos de cache serão armazenados.

```
$cep->setCacheDir('/caminho/do/cache');
```

**Parâmetros:**

- `string $path` → Caminho do diretório
- `int $permission` → Permissão (padrão: `0777`)

---

### ⏱️ setCacheTTL

[](#️-setcachettl)

Define o tempo de vida do cache em segundos.

```
$cep->setCacheTTL(3600); // 1 hora
```

---

### 🔍 getCEP

[](#-getcep)

Realiza a consulta do CEP.

```
$erro = $cep->getCEP('01001000');
```

**Retorno:**

- `false` → Sucesso
- `string` → Mensagem de erro

---

📍 Métodos de Dados
------------------

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

Após uma consulta bem-sucedida (`getCEP`), os dados podem ser acessados:

---

### 🏠 Endereço

[](#-endereço)

```
$cep->getLogradouro();
$cep->getComplemento();
$cep->getUnidade();
$cep->getBairro();
```

---

### 🌆 Localização

[](#-localização)

```
$cep->getLocalidade();
$cep->getUF();
$cep->getEstado();
$cep->getRegiao();
```

---

### 🏛️ Informações adicionais

[](#️-informações-adicionais)

```
$cep->getIBGE();
$cep->getGIA();
$cep->getDDD();
$cep->getSIAFI();
```

---

💡 Exemplo completo
------------------

[](#-exemplo-completo)

```
use MGCEP\MGCEP;

$cep = new MGCEP();
$cep->setCacheDir(__DIR__ . '/cache');
$cep->setCacheTTL(86400); // 1 dia

$erro = $cep->getCEP('01001000');

if ($erro) {
    echo "Erro: $erro";
    exit;
}

echo 'Rua: ' . $cep->getLogradouro() . PHP_EOL;
echo 'Bairro: ' . $cep->getBairro() . PHP_EOL;
echo 'Cidade: ' . $cep->getLocalidade() . PHP_EOL;
echo 'UF: ' . $cep->getUF() . PHP_EOL;
```

---

⚠️ Observações
--------------

[](#️-observações)

- É necessário chamar `getCEP()` antes de acessar os métodos de dados
- O cache é baseado no **hash da URL**
- Arquivos expirados são removidos automaticamente
- Requer conexão com internet na primeira consulta

---

💙 Apoie
-------

[](#-apoie)

- GitHub:
- More:

👤 Autor
-------

[](#-autor)

**Murilo Gomes Julio**

🔗

📺

---

License
-------

[](#license)

The MGCEP is provided under:

[SPDX-License-Identifier: LGPL-2.1-only](https://github.com/mugomes/mgcep/blob/main/LICENSE)

Beign under the terms of the GNU Lesser General Public License version 2.1 only.

All contributions to the MGCEP are subject to this license.

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance88

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

88d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e782d9d31b820ca2583dce523269edf91ef2db0d5c48af08384fad35324643cd?d=identicon)[bluice](/maintainers/bluice)

---

Top Contributors

[![bluiceoficial](https://avatars.githubusercontent.com/u/214032302?v=4)](https://github.com/bluiceoficial "bluiceoficial (8 commits)")

### Embed Badge

![Health badge](/badges/mugomes-mgcep/health.svg)

```
[![Health](https://phpackages.com/badges/mugomes-mgcep/health.svg)](https://phpackages.com/packages/mugomes-mgcep)
```

###  Alternatives

[symfony/config

Helps you find, load, combine, autofill and validate configuration values of any kind

4.3k479.6M8.7k](/packages/symfony-config)[matthiasmullie/minify

CSS & JavaScript minifier, in PHP. Removes whitespace, strips comments, combines files (incl. @import statements and small assets in CSS files), and optimizes/shortens a few common programming patterns.

2.0k33.1M470](/packages/matthiasmullie-minify)[jaeger/querylist-phantomjs

QueryList Plugin: Use PhantomJS to crawl Javascript dynamically rendered pages.(headless WebKit ) 使用PhantomJS采集JavaScript动态渲染的页面

6124.4k2](/packages/jaeger-querylist-phantomjs)[hieu-le/laravel-menu

Help to build menus easier in Laravel applications

102.9k1](/packages/hieu-le-laravel-menu)

PHPackages © 2026

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