PHPackages                             yzpeedro/viacep-hardcore - 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. [API Development](/categories/api)
4. /
5. yzpeedro/viacep-hardcore

ActiveLibrary[API Development](/categories/api)

yzpeedro/viacep-hardcore
========================

A hardcore PHP library for accessing the ViaCEP API.

1.1.0.x-dev(9mo ago)10MITPHPPHP ^8.1CI passing

Since Jul 22Pushed 9mo agoCompare

[ Source](https://github.com/yzPeedro/viacep-hardcore)[ Packagist](https://packagist.org/packages/yzpeedro/viacep-hardcore)[ Docs](https://github.com/yzpeedro/viacep-hardcore)[ RSS](/packages/yzpeedro-viacep-hardcore/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (6)Versions (3)Used By (0)

🧠 ViaCEP Hardcore
=================

[](#-viacep-hardcore)

[![Tests](https://github.com/yzpeedro/viacep-hardcore/actions/workflows/php.yml/badge.svg)](https://github.com/yzpeedro/viacep-hardcore/actions)[![Latest Version](https://camo.githubusercontent.com/2c69efc9ddbdad4b3bd763a01d91cb0e5f7322e653c2d961e0ac12548fd7c90d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f797a70656564726f2f7669616365702d68617264636f72652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/yzpeedro/viacep-hardcore)[![License](https://camo.githubusercontent.com/c54b379b912b102ca3a573cc48c91aa2cca168d72247b616961d91452754eb93/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f797a70656564726f2f7669616365702d68617264636f72652e7376673f7374796c653d666c61742d737175617265)](https://github.com/yzpeedro/viacep-hardcore/blob/main/LICENSE)

Uma biblioteca **hardcore** e moderna em php para consumir a api [ViaCEP](https://viacep.com.br), com tipagem forte, validações e foco em testes.

---

🚀 Instalação
------------

[](#-instalação)

```
composer require yzpeedro/viacep-hardcore
```

🧩 Uso básico
------------

[](#-uso-básico)

```
use Yzpeedro\ViaCepHardcore\ViaCep;

$viaCep = new ViaCep('12345678'); // substitua pelo CEP desejado
$response = $viaCep->completeResponseObject();

echo $response->data->cep; // 12345678
echo $response->data->logradouro; // Rua Exemplo
echo $response->data->bairro; // Bairro Exemplo
```

✅ Recursos
----------

[](#-recursos)

- Suporte completo ao retorno da api ViaCEP
- Integração com Guzzle
- Validações e exceptions específicas
- Cobertura de testes com PHPUnit
- Análise Estática com PHPStan
- Fixer PSR12 configurado

🧪 Testando localmente
---------------------

[](#-testando-localmente)

Para rodar os testes localmente, você precisa ter o [Composer](https://getcomposer.org/) instalado. Após isso, execute os seguintes comandos:

```
composer install
composer test
```

> isso executa: php-cs-fixer (formatação), phpstan (análise estática), phpunit (testes)

📦 autoload
----------

[](#-autoload)

```
{
  "autoload": {
    "psr-4": {
      "Yzpeedro\\ViacepHardcore\\": "src/"
    }
  }
}
```

🤝 contribuindo
--------------

[](#-contribuindo)

Sinta-se à vontade para abrir issues ou pull requests. Sugestões são bem-vindas!

🎯 Conclusão
-----------

[](#-conclusão)

Esse pacote nasceu como um exercício técnico e uma pequena provocação sobre **over engineering** — porque, sejamos honestos: consultar o ViaCEP poderia ser feito com uma simples chamada `file_get_contents()` e um `json_decode()`, a ideia aqui foi levar essa tarefa trivial ao extremo, aplicando **boas práticas**, **tipagem forte**, **validações rigorosas**, **testes**, **exceptions específicas**, **autoloader organizado**, **ci**, entre outros detalhes. Mas atenção: **não recomendo esse nível de complexidade para problemas simples no seu dia a dia**. o objetivo deste pacote é **didático**, não prescritivo. Se ele for útil para você — ótimo! Ele está pronto para produção e pode ser usado com tranquilidade.
Mas, acima de tudo, espero que ele te inspire a pensar sobre **quando vale a pena aplicar engenharia mais elaborada... e quando não vale**. Contribuições e reflexões são sempre bem-vindas 🙌

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance56

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

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

Every ~0 days

Total

2

Last Release

292d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8eeb26082a8900c70b0beec9d7856932f04850fdfce073f93dcb2d84d9531fff?d=identicon)[yzPeedro](/maintainers/yzPeedro)

---

Top Contributors

[![yzPeedro](https://avatars.githubusercontent.com/u/54516747?v=4)](https://github.com/yzPeedro "yzPeedro (10 commits)")

---

Tags

phpaddresslibrarycepviacep

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/yzpeedro-viacep-hardcore/health.svg)

```
[![Health](https://phpackages.com/badges/yzpeedro-viacep-hardcore/health.svg)](https://phpackages.com/packages/yzpeedro-viacep-hardcore)
```

###  Alternatives

[checkout/checkout-sdk-php

Checkout.com SDK for PHP

553.3M7](/packages/checkout-checkout-sdk-php)[getjump/vk

Library for work with API Vk.com

20048.5k](/packages/getjump-vk)[telegram-bot-php/core

A PHP library that makes using Telegram Bot API much easier.

60293.1k](/packages/telegram-bot-php-core)[maxbeckers/amazon-alexa-php

Php library for amazon echo (alexa) skill development.

11554.0k2](/packages/maxbeckers-amazon-alexa-php)[fabian-beiner/todoist-php-api-library

A PHP client library that provides a native interface to the official Todoist REST API.

4810.8k](/packages/fabian-beiner-todoist-php-api-library)[nkl-kst/the-sports-db

PHP library to get sports data from TheSportsDB (https://www.thesportsdb.com)

271.2k](/packages/nkl-kst-the-sports-db)

PHPackages © 2026

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