@cristianomzn/brasoes-e-bandeiras-do-brasil

Brasões e Bandeiras do Brasil

Acervo de imagens dos brasões de armas dos municípios brasileiros, destinado ao uso na DANFSE (Documento Auxiliar Nota fiscal de serviço eletrônica) e em outros documentos que exigem a identificação visual dos municípios.

Início rápido

PHP

composer require cristianomzn/brasoes-e-bandeiras-do-brasil

<?php
require 'vendor/autoload.php';

use CristianoMzn\Bbb\Bbb;

echo Bbb::get('SP', '3550308');
// /caminho/do/projeto/vendor/cristianomzn/brasoes-e-bandeiras-do-brasil/brasao-de-armas-municipal/SP/3550308.jpg

Node.js

npm install @cristianomzn/brasoes-e-bandeiras-do-brasil

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';

console.log(Bbb.get('SP', '3550308'));
// /caminho/do/projeto/node_modules/@cristianomzn/brasoes-e-bandeiras-do-brasil/brasao-de-armas-municipal/SP/3550308.jpg

Requisitos

Plataforma	Versão mínima
PHP	8.0+
Node.js	18+

API

Bbb.get(uf, ibgeCode)

Retorna o caminho absoluto para a imagem do brasão de armas de um município brasileiro, ou false/null se a imagem não existir no acervo.

Parâmetro	Tipo	Descrição
uf	string	Sigla da unidade federativa (ex: 'SP', 'RJ', 'MG')
ibgeCode	string | number	Código IBGE do município com exatamente 7 dígitos (ex: '3550308' ou 3550308)

Retorno: string | false (PHP) ou string | null (Node.js) — caminho absoluto para o arquivo .jpg ou false/null se a imagem não existir no acervo.

Exceções (lançadas em caso de erro na lib):

Exceção	PHP	Node.js	Motivo
UF inválida	InvalidArgumentException	Error	Sigla de estado não existe
Código IBGE inválido	InvalidArgumentException	Error	Não contém exatamente 7 dígitos
Diretório da UF não encontrado	RuntimeException	Error	Lib instalada incorretamente ou corrompida

UFs válidas: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, RJ, RN, RO, RR, RS, SC, SE, SP, TO

Exemplo: renderização HTML

PHP:

<?php
require 'vendor/autoload.php';

use CristianoMzn\Bbb\Bbb;

$uf = 'SP';
$codigoIbge = '3550308';
$brasao = Bbb::get($uf, $codigoIbge);

if ($brasao !== false) {
    $img = base64_encode(file_get_contents($brasao));
    $html = "<img src='data:image/jpeg;base64,{$img}' alt='Brasão de {$uf}'>";
} else {
    $html = "<span class='placeholder'>Brasão não disponível</span>";
}

echo $html;

Node.js:

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';
import { readFileSync } from 'fs';

const uf = 'SP';
const codigoIbge = '3550308';
const brasao = Bbb.get(uf, codigoIbge);

let html;

if (brasao !== null) {
    const img = readFileSync(brasao);
    const base64 = img.toString('base64');
    html = `<img src="data:image/jpeg;base64,${base64}" alt="Brasão de ${uf}">`;
} else {
    html = `<span class="placeholder">Brasão não disponível</span>`;
}

console.log(html);

Exemplo: geração de PDF

PHP com TCPDF:

<?php
require 'vendor/autoload.php';
require 'vendor/tcpdf/tcpdf.php';

use CristianoMzn\Bbb\Bbb;

$uf = 'SP';
$codigoIbge = '3550308';
$brasao = Bbb::get($uf, $codigoIbge);

$pdf = new TCPDF();
$pdf->AddPage();

if ($brasao !== false) {
    $pdf->Image($brasao, 10, 10, 30);
} else {
    $pdf->Cell(0, 10, 'Brasão não disponível para este município.', 0, 1, 'C');
}

$pdf->Output('documento.pdf');

Node.js com PDFKit:

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';
import PDFDocument from 'pdfkit';
import { createWriteStream } from 'fs';

const uf = 'SP';
const codigoIbge = '3550308';
const brasao = Bbb.get(uf, codigoIbge);

const doc = new PDFDocument();
doc.pipe(createWriteStream('documento.pdf'));

if (brasao !== null) {
    doc.image(brasao, 10, 10, { width: 30 });
} else {
    doc.fontSize(12).text('Brasão não disponível para este município.', 10, 20);
}

doc.end();

Tratamento de erros

A função lança erro quando:

• A UF fornecida não é válida
• O código IBGE não contém exatamente 7 dígitos
• O diretório da UF não existe (lib corrompida)

PHP:

<?php
require 'vendor/autoload.php';

use CristianoMzn\Bbb\Bbb;

try {
    $path = Bbb::get('XX', '1234567');
} catch (InvalidArgumentException $e) {
    // UF ou código IBGE com formato inválido
    echo "Erro de validação: " . $e->getMessage();
} catch (RuntimeException $e) {
    // Diretório não existe — lib corrompida
    echo "Erro de instalação: " . $e->getMessage();
}

Node.js:

import { Bbb } from '@cristianomzn/brasoes-e-bandeiras-do-brasil';

try {
    const path = Bbb.get('XX', '1234567');
} catch (e) {
    console.error(`Erro: ${e.message}`);
}

Estrutura do projeto

brasao-de-armas-municipal/
├── AC/
│   ├── 1200054.jpg
│   ├── 1200104.jpg
│   └── ...
├── AL/
│   ├── 2700105.jpg
│   └── ...
├── GO/
│   ├── 5200050.jpg
│   └── ...
└── ...

As imagens são organizadas por unidade federativa (UF) e nomeadas pelo código IBGE do município.

Formato das imagens

Propriedade	Valor
Formato	JPEG
Resolução	192 × 192 px
Fundo	Branco

As imagens seguem o layout sugerido para inserção na DANFSE.

Cobertura atual

Resumo geral

Métrica	Valor
Total de imagens	3.266
Estados cobertos	27
Municípios abrangidos	3.266
Total de municípios no Brasil	5.569
Cobertura nacional	58,6%

Detalhamento por UF

UF	Cobertos	Total	Cobertura
RR	15	15	100%	█████████████
RS	433	497	87,1%	███████████░░
SP	554	645	85,9%	███████████░░
RJ	75	92	81,5%	██████████░░░
PB	180	223	80,7%	██████████░░░
SC	214	295	72,5%	█████████░░░░
MG	607	853	71,2%	█████████░░░░
RO	34	52	65,4%	████████░░░░░
ES	51	78	65,4%	████████░░░░░
RN	106	167	63,5%	████████░░░░░
CE	100	184	54,3%	███████░░░░░░
AL	49	102	48,0%	██████░░░░░░░
AC	10	22	45,5%	██████░░░░░░░
AM	28	62	45,2%	██████░░░░░░░
SE	34	75	45,3%	██████░░░░░░░
MS	35	79	44,3%	█████░░░░░░░░
GO	107	246	43,5%	█████░░░░░░░░
MT	60	142	42,3%	█████░░░░░░░░
PA	60	144	41,7%	█████░░░░░░░░
PR	196	399	49,1%	██████░░░░░░░
BA	146	417	35,0%	█████░░░░░░░░
PE	58	184	31,5%	████░░░░░░░░░
AP	5	16	31,3%	████░░░░░░░░░
MA	45	217	20,7%	███░░░░░░░░░░
TO	23	139	16,5%	██░░░░░░░░░░░
PI	40	224	17,9%	██░░░░░░░░░░░
DF - Brasília	1	1	100%	█████████████

Como contribuir

Contribuições são muito bem-vindas! Os principais tipos de contribuição esperados são:

• Enviar imagens de brasões de municípios ainda ausentes no acervo.
• Substituir imagens existentes por versões mais legíveis e de maior qualidade.

Regras obrigatórias

• Formato: JPEG (extensão .jpg).
• Resolução: 192 × 192 px exatos.
• Proporção de aspecto original preservada — imagens com distorção (esticamento ou compressão) serão rejeitadas.
• Nome do arquivo: código IBGE do município (ex: 1200054.jpg).
• A imagem deve ser de domínio público ou licenciada para uso livre.
• Incluir a fonte da imagem no pull request (ex: Wikipédia, portal da prefeitura).

Passo a passo

1. Faça um fork do repositório.
2. Adicione ou substitua a imagem na pasta da UF correspondente.
3. Abra um pull request com a descrição da alteração e a fonte da imagem.

Fontes

As imagens são obtidas de fontes públicas na internet, como:

• Wikipédia
• Portais oficiais de prefeituras municipais
• Outras fontes de domínio público

Importante: Somente imagens de domínio público ou licenciadas para uso livre serão aceitas neste projeto.

Ao contribuir, informe a origem da imagem utilizada.

Licença

Este projeto está licenciado sob a Licença MIT.