README

Um pacote SOLID para busca de CEP no Laravel com múltiplos provedores e fallback automático.

📦 Instalação

```bash composer require paulosanda/laravel-multiple-cep-api ```

O pacote usa Package Discovery do Laravel. Não precisa registrar manualmente.

🚀 Uso Básico

```php use PauloSanda\MultipleCepApi\CepService;

$cepService = app(CepService::class); $endereco = $cepService->search('01001000');

// Ou via Facade (se configurada no composer.json): // $endereco = \Cep::search('01001-000');

if ($endereco) { echo $endereco['logradouro']; // Rua echo $endereco['bairro']; // Bairro
echo $endereco['cidade']; // Cidade echo $endereco['estado']; // Estado echo $endereco['provider']; // Provedor que encontrou } ```

⚙️ Configuração (Opcional)

```bash php artisan vendor:publish --tag=cep-config ```

Edite `config/cep.php`:

```php return [ 'providers' => [ \PauloSanda\MultipleCepApi\Providers\ViaCepProvider::class, \PauloSanda\MultipleCepApi\Providers\BrasilApiProvider::class, \PauloSanda\MultipleCepApi\Providers\OpenCepProvider::class, // Adicione provedores customizados aqui ], 'timeout' => 3, 'retry_attempts' => 3, ]; ```

🔌 Provedores Padrão

Provedor	Prioridade	Fallback	Formato
ViaCEP	100	Sim	Qualquer
BrasilAPI	90	Sim	Apenas números
OpenCEP	80	Não	Apenas números

🛠️ Criando Provedores Customizados

Implemente a interface:

```php use PauloSanda\MultipleCepApi\Contracts\CepProviderInterface; use PauloSanda\MultipleCepApi\Utils\CepFormatter;

class MeuProvedorCustomizado implements CepProviderInterface { public function search(string $cep): ?array { // Sua implementação }

public function hasFallback(): bool
{
    return true;
}

public function getName(): string
{
    return 'MeuProvedor';
}

public function getPriority(): int
{
    return 95;
}

public function getRequireCepFormat(): ?string
{
    return CepFormatter::JUST_NUMBERS;
}

} ```

Adicione ao config:

```php 'providers' => [ \PauloSanda\MultipleCepApi\Providers\ViaCepProvider::class, \App\Providers\MeuProvedorCustomizado::class, \PauloSanda\MultipleCepApi\Providers\BrasilApiProvider::class, ], ```

⚠️ Importante

Este pacote usa Facades do Laravel (`Http`, `Log`):

Funciona apenas dentro de aplicações Laravel
Testes via CLI puro não funcionam sem Laravel

📁 Estrutura

``` src/ ├── CepService.php # Serviço principal ├── CepServiceProvider.php # ServiceProvider ├── Contracts/ │ └── CepProviderInterface.php ├── Providers/ │ ├── ViaCepProvider.php │ ├── BrasilApiProvider.php
│ └── OpenCepProvider.php ├── Utils/ │ └── CepFormatter.php └── Facades/ └── Cep.php ```

🔧 Princípios SOLID

Single Responsibility: Cada classe tem uma responsabilidade
Open/Closed: Aberto para novos provedores
Liskov Substitution: Provedores substituíveis
Interface Segregation: Interface específica
Dependency Inversion: Depende de abstrações

🤝 Contribuindo

Fork o projeto
Crie uma branch (`git checkout -b feature/MinhaFeature`)
Commit (`git commit -m 'Adiciona MinhaFeature'`)
Push (`git push origin feature/MinhaFeature`)
Abra um Pull Request

📄 Licença

MIT - veja LICENSE para detalhes.

👨‍💻 Autor

Paulo Sanda - GitHub

paulosanda / laravel-multiple-cep-api

Maintainers

Package info

Statistics

Security