TOPICOS - Boleto Library PHP

Como Usar e Integrar esta Biblioteca à Sua Aplicação
Reportando Bugs, Pedindo Ajuda e Fazendo Sugestões
Implementando novos Bancos e Carteiras
Contribuindo com a Biblioteca Principal
Testes de Unidades (Simple Test)
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:

$ cd boleto-lib
$ cd bancos
$ 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:

Extraia o arquivo baixado em ../boleto-lib/bancos
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:

Existe pelo menos um plugin de banco instalado
Os plugins de bancos presentes estão instalados corretamente e
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 <[email protected]>
 */

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:

$ git tag v1.x-1.0 -m "Beta1"
$ 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

5. TESTES DE UNIDADES (SIMPLE TEST)

6. QUEM USA ESTA BIBLIOTECA

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.

jonasporto / boleto Goto Github PK

boleto's Introduction

TOPICOS - Boleto Library PHP

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

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

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

3. IMPLEMENTANDO NOVOS BANCOS E CARTEIRAS

Especificação do Número Febraban.

4. CONTRIBUINDO COM A BIBLIOTECA PRINCIPAL

5. TESTES DE UNIDADES (SIMPLE TEST)

6. QUEM USA ESTA BIBLIOTECA

boleto's People

Contributors

Watchers

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent