README

Pacote PHP 8.2 para download e parse das cotações de fechamento de câmbio do Banco Central do Brasil (BCB).

Requisitos

PHP 8.2+
ext-curl

Instalação

composer require atlantic/cotacao-bcb

Uso básico

use Atlantic\CotacaoBcb\CotacaoBcb;

$bcb = new CotacaoBcb();
$resultado = $bcb->buscar(new DateTimeImmutable('2026-04-17'));

$resultado->data;                          // DateTimeImmutable — data efetiva da cotação
$resultado->cotacoes;                      // array<string, CotacaoDto> indexado por sigla
$resultado->cotacoes['USD']->taxaCompra;   // float
$resultado->cotacoes['USD']->taxaVenda;    // float
$resultado->cotacoes['EUR']->taxaCompra;   // float

Regras de negócio

Situação	Comportamento
Sábado ou domingo	Retorna a cotação da sexta-feira anterior
Data de hoje ou futura	Retorna a cotação do último dia útil anterior
Feriado bancário	Lança `CotacaoNaoEncontradaException`
Falha de conexão / HTTP	Lança `BcbIndisponivelException`

Tratamento de exceções

use Atlantic\CotacaoBcb\Exception\CotacaoNaoEncontradaException;
use Atlantic\CotacaoBcb\Exception\BcbIndisponivelException;

try {
    $resultado = $bcb->buscar(new DateTimeImmutable('2026-01-01')); // Ano Novo
} catch (CotacaoNaoEncontradaException $e) {
    // BCB retornou 404 — feriado ou data sem cotação disponível
} catch (BcbIndisponivelException $e) {
    // Falha de conexão ou erro HTTP inesperado
}

Estrutura do retorno

`ResultadoCotacaoDto`

Propriedade	Tipo	Descrição
`data`	`DateTimeImmutable`	Data efetiva da cotação (após ajuste de dia útil)
`cotacoes`	`array<string, CotacaoDto>`	Todas as moedas, indexadas pela sigla ISO (ex: `'USD'`)

`CotacaoDto`

Propriedade	Tipo	Descrição
`sigla`	`string`	Código ISO da moeda (ex: `USD`, `EUR`)
`codigo`	`int`	Código numérico do BCB
`tipo`	`string`	Tipo de paridade (`A` ou `B`)
`taxaCompra`	`float`	Taxa de compra em BRL
`taxaVenda`	`float`	Taxa de venda em BRL
`paridadeCompra`	`float`	Paridade de compra
`paridadeVenda`	`float`	Paridade de venda
`data`	`DateTimeImmutable`	Data da cotação

Injeção de dependência

O repositório HTTP pode ser substituído por uma implementação customizada (útil para testes):

use Atlantic\CotacaoBcb\Repository\CotacaoBcbRepositoryInterface;

class RepositorioFake implements CotacaoBcbRepositoryInterface
{
    public function buscar(string $data): string
    {
        return "17/04/2026;220;A;USD;4,96890000;4,96950000;1,00000000;1,00000000\n";
    }
}

$bcb = new CotacaoBcb(new RepositorioFake());

Estrutura do pacote

src/
├── CotacaoBcb.php                        → fachada principal (entry point)
├── Dto/
│   ├── CotacaoDto.php                    → cotação de uma moeda (readonly)
│   └── ResultadoCotacaoDto.php           → coleção de cotações para uma data (readonly)
├── Factory/
│   └── CotacaoDtoFactory.php             → cria CotacaoDto a partir de linha CSV
├── Repository/
│   ├── CotacaoBcbRepository.php          → busca CSV via HTTP (cURL)
│   └── CotacaoBcbRepositoryInterface.php → abstração do repositório
├── Service/
│   ├── BuscadorCotacaoService.php        → orquestra lógica de negócio e datas
│   └── ParserCsvService.php              → faz parse do conteúdo CSV
├── ValueObject/
│   └── DataCotacao.php                   → value object de data com regra de dia útil
└── Exception/
    ├── CotacaoNaoEncontradaException.php → 404 do BCB
    └── BcbIndisponivelException.php      → falha de conexão/HTTP

Ferramentas de qualidade

vendor/bin/phpunit          # testes unitários
vendor/bin/phpstan analyse  # análise estática
vendor/bin/phpcs            # code style PSR-12

Fonte dos dados

CSV de fechamento do BCB: https://www4.bcb.gov.br/Download/fechamento/{YYYYMMDD}.csv

Licença

MIT

pereirapthiago / cotacao-bcb

Package info

Security

Statistics