OpenBoleto – Biblioteca de boletos bancários em PHP

Written on 
Latest release GitHub Stars

O OpenBoleto é uma biblioteca de código aberto para geração de boletos bancários, um meio de pagamento muito comum no Brasil. O foco é ser simples e ter uma arquitetura compatível com os recursos mais modernos do PHP, mais amigável com frameworks MVC. Criada em Janeiro de 2013, hoje finalmente lançamos a primeira versão estável.

Como usar?

O OpenBoleto é simples e flexível, serve tanto para quem não tem tanta experiência em programação quanto para quem manja dos paranauê gosta de customizar tudo. Veja um exemplo abaixo de como gerar um boleto para o Banco do Brasil:

<?php

use OpenBoleto\Banco\BancoDoBrasil;
use OpenBoleto\Agente;

$sacado = new Agente('Fernando Maia', '023.434.234-34', 'ABC 302 Bloco N', '72000-000', 'Brasília', 'DF');
$cedente = new Agente('Empresa de cosméticos LTDA', '02.123.123/0001-11', 'CLS 403 Lj 23', '71000-000', 'Brasília', 'DF');

$boleto = new BancoDoBrasil(array(
    // Parâmetros obrigatórios
    'dataVencimento' => new DateTime('2013-01-24'),
    'valor' => 23.00,
    'sequencial' => 1234567, // Para gerar o nosso número
    'sacado' => $sacado,
    'cedente' => $cedente,
    'agencia' => 1724, // Até 4 dígitos
    'carteira' => 18,
    'conta' => 10403005, // Até 8 dígitos
    'convenio' => 1234, // 4, 6 ou 7 dígitos
));

echo $boleto->getOutput();

Sim, é só isso! :) Claro que existem outras opções configuráveis, para saber as específicas de cada banco, consulte a pasta samples.

Note que o sufixo “Dv” se refere à dígito verificador. Todos os parâmetros para geração podem ser acessados via getters e setters, por exemplo:

$agencia = $boleto->getAgencia();
$boleto->setAgencia(1584);

Instalação

Composer

Se você já conhece o Composer (o que é extremamente recomendado), simplesmente adicione a dependência abaixo à diretiva “require” seu composer.json:

{
  "openboleto/openboleto": "v1.0"
}

Como library de algum framework

Primeiro baixe ou clone o repositório no GitHub. Se você usa algum framework com autoloader, basta apontar o namespace ‘OpenBoleto’ para a pasta ‘src’. Ou simplesmente mova o conteúdo da pasta ‘src’ para a library de seu framework.

Com PHP puro (biblioteca standalone)

Caso não use framework ou nenhum autoloader, ou você simplesmente quer dar “um include e pronto”, você pode usar o autoloader incluso na biblioteca, para isso simplesmente dê um include no arquivo “autoloader.php” e tudo deverá funcionar normalmente!

Bancos suportados

Atualmente estão suportados os seguintes bancos:

Você também pode ajudar adaptando a outros bancos, o processo consiste basicamente em identificar o modo pelo qual o banco gera o seu campo livre, ou seja, o campo de 20 a 44 do código de barras. Desta forma, basta implementar em uma classe observando outros atributos como código do banco. Como exemplo, veja a classe Bradesco.

Algumas considerações

O método getNossoNumero é read-only, ou seja, não existe um setNossoNumero. Por que isso? Alguns bancos geram o nosso número, aquele que fica impresso no boleto, de forma diferente do código único que você define por boleto.

Para evitar confusões, definimos que o código único por boleto se chama sequencial. Nosso número é aquele que aparece no boleto, e geralmente é o que vem nos arquivos de retorno do banco.

#TODO

Toda contribuição é muito bem vinda! Note que os padrões de codificação utilizados são os PSR-0, PSR-1 e PSR-2.

Agradecimentos

Agradeço aos mantenedores das bibliotecas BoletoPHP e Boleto Library PHP, principalmente à este último que explica muito bem como funciona a geração de boletos e foi de grande inspiração para a abstração do OpenBoleto. Agradeço também por toda comunidade que apoia e contribui para o projeto. E por último, mas não menos importante ao Cristiano Teles, coordenador da comunidade PHP-DF e grande e inspirador mentor com o qual tive o privilégio de aprender muitas das coisas aqui postas em prática.

Licença

Este projeto é de código aberto licenciado pela MIT License.