Boleto Library PHP - Brazilian Payment Method
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bancos
docs
imagens
unit-testing
.gitignore
Boleto.class.php
COPYRIGHT.txt
LICENSE.txt
README.md
boleto.tpl.php
style.css

README.md

Boleto Library Logo

TOPICOS - Boleto Library PHP

  1. Como Usar e Integrar esta Biblioteca à Sua Aplicação
  2. Reportando Bugs, Pedindo Ajuda e Fazendo Sugestões
  3. Implementando novos Bancos e Carteiras
  4. Contribuindo com a Biblioteca Principal
  5. Testes de Unidades (Simple Test)
  6. Quem Usa Esta Biblioteca

1. COMO USAR E INTEGRAR ESTA BIBLIOTECA À SUA APLICAÇÃO

1.1 Vá até a pasta pública do seu servidor e baixe a cópia mais recente desta biblioteca com o seguinte comando:
$ git clone --branch 1.x-dev https://github.com/drupalista-br/boleto.git boleto-lib

ou faça o Download da última versão estável em https://github.com/drupalista-br/Boleto/tags


1.2 Instale pelo menos um plugin de um banco com os seguintes comandos:

  1. $ cd boleto-lib
  2. $ cd bancos
  3. $ git clone --branch 1.x-1.x-dev https://github.com/USUARIO/Boleto-XXX.git XXX

Onde XXX deverá ser substituido pelo código do Banco e USUARIO ser substituido pelo nome do usuário que é o mantenedor do plugin do banco.

ou faça o Download da última versão estável do plugin em https://github.com/drupalista-br/Boleto/tree/1.x-dev/bancos e:

  1. Extraia o arquivo baixado em ../boleto-lib/bancos
  2. Renomeie a pasta extraida com código do Banco ao qual o plugin pertence.
    Exemplo: ../boleto-lib/bancos/001 para o Banco do Brasil.

1.3 Para integrar esta biblioteca a qualquer aplicação PHP você precisará usar apenas dois métodos. São eles:

Para mais informações sobre todos os métodos setters and getters disponíveis, acesse a Documentação do API

Boleto::load_boleto($argumentos = array()) Este método é usado para instanciar um novo objeto.
Note que este método é chamado estaticamente.
output($render = TRUE) Este método gera o html do boleto.

Se você passar o parâmetro FALSE então
somente a propriedade $boleto->output é populada mas o html não é gerado.
Neste caso use o método outputPropertyGetter() para salvar o output
em uma variável. Por exemplo:
$output = $boleto->outputPropertyGetter();
  • O seu código de integração deverá ter esta estrutura:

Note que apesar de todos os possíveis valores dos argumentos estarem listados abaixo, nem sempre você precisa enviar todos eles, veja a documentação de cada plugin para determinar o que obrigatoriamente precisa ser enviado.

Faça o download do exemplo abaixo em https://gist.github.com/3167145

<?php

include_once '../boleto-lib/Boleto.class.php';

$argumentos = array(
  'bank_code' => '104',
  'agencia' => 1234,
  'agencia_dv' => '2',
  'conta' => 12345678901,
  'conta_dv' => 3,
  'valor_boleto' => '2952.95',
  'numero_documento' => '27030195',
  'endereco' => 'street name and number',
  'cidade_uf'=> 'city and state',
  'cedente'  => 'ABC Company Ltd',
  'sacado' => 'John Doe',
  'carteira' => 'A',
  'carteira_nosso_numero' => '80',
  'nosso_numero' => '12345678',
  'cpf_cnpj' => '000.000.000-00', 
  'endereco1' => 'street name and number',
  'endereco2' => 'city and state',
  'demonstrativo1' => 'Your text here',
  'demonstrativo2' => 'Your text here',
  'demonstrativo3' => 'Your text here',
  'instrucoes1' => 'Your text here',
  'instrucoes2' => 'Your text here',
  'instrucoes3' => 'Your text here',
  'instrucoes4' => 'Your text here',
  'data_vencimento' => '25-07-2011',
  'desconto_abatimento' => '0.00',
  'outras_deducoes' => '0.00',
  'mora_multa' => '0.00',
  'outros_acrescimos' => '50.55',
  'title' => 'My title',
  'local_pagamento' => 'Your text here',
  'especie' => 'Your value here',
  'quantidade' => 'Your value here',
  'valor_unitario' => 'Your value here',
  'especie_doc' => 'Your value here',
  'data_processamento' => 'dd/mm/yyy',
  'avalista' => 'Michael Jackson',
  'aceite'=> 'Your value here',
  'merchant_logo' => 'images/logo.jpg',
);

// Instancia o objeto.
$boleto = Boleto::load_boleto($argumentos);

// Verifica se tudo correu bem.
if (is_object($boleto)) {
  // Imprime o boleto.
  $boleto->output();
}
else {
  // Seu error handler pois algo deu errado.
}

Encontre exemplos na pasta ../boleto-lib/bancos/XXX/example.php. Para ver a demonstração acesse:

http://localhost/boleto-lib/bancos/XXX/example.php

Onde XXX é o código do banco.

  • Outro exemplo de como usar o seu próprio html template customizado:

Faça o download deste example em https://gist.github.com/3167695

<?php

include_once 'boleto-lib/Boleto.class.php';

$argumentos = array(
  // Argumentos aqui.
);

// Instancia o objeto.
$boleto = Boleto::load_boleto($argumentos);

// Verifica se tudo correu bem.
if (is_object($boleto)) {
  // Use o arquivo boleto.tpl.php como exemplo para criar o seu template customizado.
  $settings = array('template' => '/home/minha_pasta/meu_layout_template.php');

  // Informa ao objeto a localização do seu template customizado.
  $boleto->settingsPropertySetter($settings);

  // Imprime o boleto.
  $boleto->output();
else {
  // Seu error handler pois algo deu errado.
}

Antes de instanciar um objeto talvés seja interessante a sua aplicação verificar se:

  1. Existe pelo menos um plugin de banco instalado
  2. Os plugins de bancos presentes estão instalados corretamente e
  3. Saber quais são os plugins de bancos que estão presentes e corretamente instalados.

Para isto existe o método Boleto::installedPlugins() que retorna uma array com os códigos dos bancos os quais possuem plugin corretamente instalados.

Note que este método deve ser chamado estáticamente.

2. REPORTANDO BUGS, PEDINDO AJUDA E FAZENDO SUGESTÕES

Abra chamados em https://github.com/drupalista-br/boleto/issues

3. IMPLEMENTANDO NOVOS BANCOS E CARTEIRAS

NOTA: Caso você queira alterar ou adicionar uma nova carteira a um plugin de banco já existente, então vá direto para o passo 4.6.

3.1 Dentro da pasta ../boleto/bancos crie uma subpasta e a nomeie com o código do banco que você irá implementar. Por exemplo:

../boleto/bancos/237


3.2 Crie os seguintes arquivos dentro da subpasta que acabou de criar:

Obrigatório Banco_XXX.php Onde XXX é o código do banco
Obrigatório logo.jpg Logo marca do banco
Obrigatório README.txt ou README.md Instruções sobre a formatação dos campos do Boleto para este banco. Pode-se usar README.md ao invés de README.txt. Saiba mais sobre Markdown em http://github.github.com/github-flavored-markdown
opcional layout.tpl.php Se este arquivo existir então o template padrão será desconsiderado e este template será usado. Veja a implementação do Banco do Brasil como exemplo
opcional style.css Mesmo caso do layout.tpl.php. Dê uma olhada na implementação do Banco do Brasil como exemplo
obrigatório example.php Não é obrigatório adicionar código de exemplo, mas este arquivo precisa existir, mesmo que vazio. Este arquivo serve como "use case" para as pessoas poderem ver como fica o boleto gerado por seu plugin acessando `http://localhost/boleto-lib/bancos/XXX/example.php`. Onde XXX é o código do banco.
    Veja o exemplo do plugin da Caixa Econômica Federal.

    </td>
</tr>


<tr>
    <td>obrigatório</td>
    <td>unit-testing/simpletest.php</td>
    <td>Veja exemplo de código logo abaixo.</td>
</tr>

3.3 O arquivo unit-testing/simpletest.php deverá conter no mínimo o seguinte código:

Faça o download do exemplo abaixo em https://gist.github.com/3167313

<?php
/**
* @file
* Unit testing.
*/

require_once "../../../unit-testing/boleto.test.php";

class TestOfXXX extends BoletoTestCase{
  protected $mockingArguments;

  function mockingArguments() {
    $this->mockingArguments = array(
      array(
        // Argumentos do Primeiro test case.
      ),
      array(
        // Argumentos do Segundo test case.
      ),
      // E assim por diante. Dê uma olhada no simpletest.php do
      // Banco do Brasil para um exemplo com mais de um test case.
    );
  }
}

Onde XXX em TestOfXXX é o código do banco.


3.4 Na classe Banco_XXX que acabara de criar você precisa implementar os seguintes métodos:

Obrigatório setUp() Você precisa no mínimo popular a propriedade $this->bank_name com o nome do banco.
Obrigatório febraban_20to44() A linha digitável e o código de barras são calculados com base num número com 44 digitos chamado de especificação febraban. Veja abaixo como este número é constituido.

As posições 1 a 19 é padrão para todos os bancos. As posições 20 a 44 é livre para os bancos armazenem as informações que quizerem e na forma que quizerem.

Assim, este método "febraban_20to44()" deverá construir este número com total de 25 digitos, de acordo com as espeficações das carteiras do banco, e armazena-lo na propriedade $this->febraban['20-44'].
opcional custom()
opcional outputValues()

Dê uma olhada nas implementações já existentes na pasta ../boleto-lib/bancos para usar como exemplo.


Especificação do Número Febraban.

Este número é a base para calcular a linha digitável e o código de barras.

Você só precisa se preocupar em calcular as posições 20 ao 44.

As posições 20 a 44 é a única coisa que diferencia boletos de um banco para outro ou mesmo de uma carteira para outra de um mesmo banco.

Posição Quant. de Dígitos Descrição
01-03 3 Código do banco sem o digito
04-04 1 Código da Moeda (9-Real)
05-05 1 Dígito verificador do número febraban
06-09 4 Fator de vencimento
10-19 10 Valor Nominal do Título
20-44 25 Campo Livre. Reservado aos bancos.

3.5 No arquivo Banco_XXX.php você deverá criar uma classe chamada Banco_XXX que extends Boleto.

Faça o download do exemplo abaixo em https://gist.github.com/3167333

A sua implementação deverá conter no mínimo o seguinte estrutura de código:

<?php
 /**
 * This code is released under the GNU General Public License.
 * See COPYRIGHT.txt and LICENSE.txt.
 *
 * @author Fulano de Tal <fulanodetal@servidor.com>
 */

class Banco_XXX extends Boleto{
  function setUp(){
    $this->bank_name  = 'Nome do Banco Sendo Implementado';
  }

  function febraban_20to44() {
    // Calcule as posições 20 a 44 do número febraban de acordo com
    // os argumentos em $this->arguments e com as regras da(s)
    // carteira(s) do banco.
    // ...

    // Salve o número com 25 digitos na propriedade febraban['20-44'].
    $this->febraban['20-44'] = $numero_calculado;
  }
}  

Onde XXX em Banco_XXX é o código do banco sendo implementado.


3.6 Recomenda-se que você nomeie o branch do seu repositório para 1.x-1.x-dev ao invés de master.

Ou seja, o primeiro 1.x refere-se à versão da biblioteca boleto a qual o seu plugin suporta e o segundo 1.x refere-se à versão do seu plugin.


3.7 Uma vez que fizer o push dos seus commits, crie também marcações ( tags ) das versões estáveis do seu plugin. Por exemplo:

  1. $ git tag v1.x-1.0 -m "Beta1"
  2. $ git push origin v1.x-1.0

3.8 Feito o release ( tag ), acesse https://github.com/drupalista-br/Boleto/issues e crie um issue solicitando a inserção do link do seu novo plugin na nossa listagem de plugins em https://github.com/drupalista-br/Boleto/tree/1.x-dev/bancos .

Não esqueça de informar o link para as tags do seu repositório.

4. CONTRIBUINDO COM A BIBLIOTECA PRINCIPAL

Leia também:

  1. Como Forkear um Repositório e Solicitar Pull Requests no Github nos links http://help.github.com/fork-a-repo e http://help.github.com/send-pull-requests
  1. Mais informações sobre as propriedades e métodos disponíveis na Documentação do API

4.1 Você deverá seguir o padrão Doxygen ao comentar o seu Código:
http://www.stack.nl/~dimitri/doxygen/docblocks.html


4.2 Acesse https://github.com/drupalista-br/boleto e clique e "Fork". Feito isto o github criará um novo repositório em sua conta contendo uma cópia do repositório Boleto.


4.3 Agora baixe o código de sua cópia forkeada com o seguinte comando:

$ git clone --branch 1.x-dev git@github.com:USUARIO/boleto.git boleto-lib

Onde USUARIO deverá ser substituido pelo seu usuario no Github.


4.4 Uma vez que você fizer as modificações / inserções / correções no código, então você deverá atualizar o seu repositório forkeado. Aqui vão os comandos:

$ git add .
$ git commit -m "Sua mensagem explicando o que foi feito"
$ git push origin 1.x-dev

A partir de agora o seu repositório forkeado possue um código diferente do repositório Boleto o qual você inicialmente fez uma cópia.

O próximo passo mostra como mergir as suas alterações para o repositíro Boleto.


4.5 Acesse o seu reposório forkeado no Github e clique em "Pull Request".

O Pull Request irá criar automaticamente um issue solicitando que o seu código seja mergido.

Uma vez que o seu código for analisado, uma das seguintes ações poderão ser tomadas:

  1. O seu pull request é aceito e o seu código é mergido ou
  2. Poderá ser solicitado que você faça algum ajuste antes que o pull request seja aceito. Neste caso basta repetir o processo do passo 4.3 e o github automaticamente insere o seu novo commit no pull request.
  3. Ou o seu pull request é recusado e o issue é fechado. Neste caso será argumentado as razões da recusa.

4.6 Caso você queira por exemplo alterar ou adicionar uma nova carteira à um plugin de banco já existente você deverá seguir os passos 4.1 ao 4.5, entretanto no passo 4.2 você irá forkear o repositório do plugin do banco em questão ao invés de forkear o repositório do Boleto.

Vale lembrar ainda que o passo 4.3 deverá ser feito dentro da pasta ../boleto/bancos e a subpasta do repositório sendo baixado deverá ser renomeada para o código do banco.

5. TESTES DE UNIDADES (SIMPLE TEST)

Leia também

  1. O que é Simple Test:
    http://pt.wikipedia.org/wiki/SimpleTest e
    http://www.simpletest.org/en/first_test_tutorial.html

Simpletest for Boleto PHP Library


5.1 Como testar

  1. Faça o download da biblioteca Simpletest e extraia o arquivo compactado em ../boleto-lib/unit-testing/simpletest

  2. No seu navegador acesse http://localhost/boleto-lib/bancos/XXX/unit-testing/simpletest.php. Onde XXX é o código do banco.

    Exemplo:
    http://localhost/boleto-lib/bancos/104/unit-testing/simpletest.php

5.2 Onde e Como escrever Testes de Unidades

O código dos Testes de Unidades estão alojados em dois locais. São eles:

  1. No arquivo de testes principal em ../boleto-lib/unit-testing/boleto.test.php e
  2. Nos arquivos localizados nas pastas de cada plugin, ../boleto-lib/bancos/XXX/unit-testing/simpletest.php. Onde XXX é o código do banco.

Provavelmente não seja necessário, mas caso queira adicionar testes de unidades em um plugin de banco, você deverá adicionar o seu código de testes, além dos elementos obrigatório do item 3.3, em ../boleto-lib/bancos/XXX/unit-testing/simpletest.php

Para que os seus métodos de teste sejam chamados você deverá colocar o prefixo test no nome de seus métodos.

Por Exemplo:

<?php
function testNomeExplicativoDoMeuTesteNoFormatoDesteExemplo() {  
   // testes aqui.  
}

Mais exemplos em http://www.simpletest.org/en/first_test_tutorial.html e também no arquivo ../boleto-lib/unit-testing/boleto.test.php

6. QUEM USA ESTA BIBLIOTECA

  1. Commerce Boleto para Drupal Commerce - http://drupal.org/project/commerce_boleto

Abra um chamado em https://github.com/drupalista-br/boleto/issues e fale a respeito do seu projeto para que ele possa ser mencionado nesta sessão.