Skip to content

realcofre/Boleto

BranchesTags

Repository files navigation

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.

About

No description, website, or topics provided.

Resources

Readme

License

GPL-2.0 license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages