Para baixar a biblioteca Boleto PHP visite https://github.com/drupalista-br/Boleto/wiki/Projeto-Boletophp-API


Ao contrário do código disponível em boboletophp.com.br , o qual foi super útil para a obtenção de informações, este pacote cotém um código otimizado no estilo OOP (Object Orienteded Programing) e a integração se dá por meio de apenas 3 linhas de código para enviar a sua lista de argumentos.

Segue abaixo o manual completo para integrar a biblioteca a sua aplicação, bem como criar novos plugins (implementações) para novos bancos e carteiras.

TOPICOS

1. Visão Geral
2. Instalação (integrar o API)
3. Reportando Bugs, Pedindo Ajuda e Fazendo Sugestões
4. Propriedades do Objeto
5. Implementando novos Bancos
6. Debugging
7. Publicando a sua Implementação

1. VISÃO GERAL

O que mudou entre Boletophp 0.17 e Boleto 1.0?

O código foi totalmente re-escrito usando o conceito de OOP;
Ficou muito mais fácil de integrar a qualquer aplicação externa utilizando-se do conceito de API. Assim o usuário desenvolvedor não precisa mexer nas bibliotecas do pacote, o que facilita ainda as atualizações;
Ficou mais simples de se implementar novos bancos bem como novas carteiras, pois a classe principal (Boleto) faz todo o trabalho pesado.


2. INSTALAÇÃO (Integrar o API)

Ao descompactar o arquivo do pacote que você baixou, terás uma pasta que conterá, entre outros, um arquivode exemplo (example.php) para integrar o API e uma subpasta chamada boleto-lib.

Esta subpasta (boleto-lib) é a nossa biblioteca.

Para fazer uso desta biblioteca em sua aplicação proceda da seguinte forma:


Copie a pasta boleto-lib para um diretorio dentro de sua pasta pública.

Por exemplo: www/bibliotecas/boleto-lib

Acesse https://github.com/drupalista-br/Boleto/wiki/Projeto-Boletophp-API e faça o download dos pacote(s) que implementa(m) o(s) os banco(s) que você trabalha para a emissão de boletos.

Vá até a pasta boleto-lib/bancos e crie uma sub pasta. O nome desta sub-pasta deverá ser o código do banco. Seguindo o nosso exemplo, se baixarmos a implementação do Banco do Brasil então ficaria assim:

www/bibliotecas/boleto-lib/001

Copie os arquivos da implementação para dentro da pasta que você criou na letra "c" acima. Novamente seguindo o nosso exemplo do Banco do Brasil, o arquivo da classe que extends Boleto ficará localizado em:

www/bibliotecas/boleto-lib/001/Banco_001.php

NOTA:
Se a implementação do banco que queira trabalhar ainda não estiver disponível então leia as instruções no item "5. IMPLEMENTANDO NOVOS BANCOS" abaixo e disponibilize o código para que este possa ser publicado no projeto.

Para integrar o Boleto API a sua aplicação, por exemplo www/gera-boleto.php (http://localhost/gera-boleto.php), proceda da seguinte forma:

* Dentro de gera-boleto.php crie uma array com os argumentos a serem passados.

N OTAS:
Veja o arquivo exemplo.php que acompanha o pacote para uma lista de todos os argumentos possíveis.

L eia o arquivo readme.txt da implementação de cada banco localizado em www/bibliotecas/boleto/boleto-lib/bancos/XXX/readme.txt onde XXX é o código do banco, para saber mas detalhes no formato e requisitos de validação de campos específicos.

Para o argumento 'library_location', em nosso exemplo, ficaria 'bibliotecas/boleto/boleto-lib'

* Inclua o arquivo da biblioteca com o seguinde código:

include_once($argumentos['library_location'].'/Boleto.class.php');

* Instancie um novo objeto. Por exemplo: $boleto = new Boleto($argumentos);

* Para imprimir as propriedades do objeto faça assim: echo '<pre>'; print_r($boleto);

v isite http://localhost/gera-boleto.php para visualizar as propriedades do objeto que vc acabou de instanciar.

* Você notará que a propriedade output (a última da estrutura) estará vazia. Veja mais detalhes em "4. PROPRIEDADES DO OBJETO" logo abaixo, mas basicamente se você quizer fazer a renderização do html chame o método output() assim:

$boleto->output();

Pronto, agora ao recarregar o seu navegador em http://localhost/gera-boleto.php será impresso o boleto.

* Agora se você precisa apenas dos valores da propriedade output para customizar a sua propria renderização, basta passar o valor FALSE na chamada do método output(). Assim:

$boleto->output(FALSE);

Logo abaixo coloque:
echo '<pre>';
print_r($boleto);

recarregue http://localhost/gera-boleto.php e verá que agora a propriedade "output" estará populada pronta para ser usada, mas o html não é renderizado desta vez.

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

A sua pergunta, sugestão ou informação de bug é muitíssimo bem vinda, entretando peço gentilmente que não envieemails para mim ou quaisquer outros colaboradores do projeto e sim poste na lista de Issues de cada repositório.

Digo "cada repositório" porque a biblioteca principal (Boleto) é um repositório assim como as implementaçõesde bancos são também, cada um deles, um repositório em separado, justamente para facilitar o desenvolvimento,melhoramento e manutenção.

A razão para se postar na lista de Issues ao invés de enviar emails é muito simples:

O projeto é uma comunidade onde todos devem participar ajudando da forma que podem, assim a sua dúvida, sugestão, pedido, erro, será de grande valia para outros que também precisam da
mesma informação, que, uma vez online, ela vai ficar lá ajundando a comunidade por toda a eternidade ;)

Postando online você poderá ser respondido por qualquer pessoa que estiver disponível, pois, como já dito, todos são encorajados a participar da forma que podem.


Tente ser descritivo no título do seu poste para que as pessoas possam encontra-lo facilmente quandoestiverem pesquisando nos issues ou mesmo no Google.

Por exemplo:
"Erro no boleto" não fica muito claro do que se trata, agora "Undefined variable $blahblah na linha 8 do arquivo blahblah ao instanciar um novo objeto" fica muito mas nitido do que se trata, e assim diminui as duplicações nos Issues.

CORRIGINDO PROBLEMAS OU MELHORANDO O CÓDIGO

Não é obrigatório mas facilita muito se ao enviar uma correção para um bug ou melhoria no código você pudesse fazer por meio de um arquivo patch. Informações em http://pt.wikipedia.org/wiki/Patch_(Unix)

Mas postar o código ou anexar arquivos que não sejam patches nos Issues também são bem vindos.

PESQUISAR ANTES DE POSTAR

Outra forma de ajudar é tomando alguns minutos do seu tempo pesquisando na lista de Issues e lendo asinstruções, tais como este readme, antes de abrir um novo Issue, pois na maioria dos casos a pergundajá possui uma resposta disponível.

4. PROPRIEDADES DO OBJETO

bank_code - Código do banco.

bank_name - Nome do Banco.

is_implemented - Informa se existe uma classe que extende a classe principal (Boleto), ou seja, se o banco está implementado. 0 = Não está implementado, 1 = Está implementado. Veja "IMPLEMENTANDO NOVOS BANCOS" logo abaixo.

A implementação de cada banco se dá por uma sub classe (child) que extende a classe Boleto (parent).

warnings - Contém mensagens que podem ajudar a identificar a causa de problemas, tais como inconsistência nos argumentos enviados, etc.

methods - Lista de todos os métodos presentes tanto na classe Boleto (parent) como na classe do banco (child)

settings - Contém valores de configuração do objeto.

arguments - Contém todos os valores dos argumentos que foram passados pela aplicação integradora bem como valores declarados como padrão que não foram explicitamente passados.

computed - Contém os valores resultantes de transformações no processo de criação do objeto.

febraban - Esta propriedade é a chave central para o cálculo da linha digitável e o código de barras. As específicações dos valores seguem esta regra:

Posições 01 a 03 - Código do banco sem o dígito (contem 3 dígitos)
Posição 04 - Código da Moeda (9-Real) (contem 1 dígito)
Posição 05 - Dígito verificador do código de barras (contem 1 dígito)
Posição 06 a 09 - Fator de vencimento (contem 4 dígitos)
Posições 10 a 19 - Valor Nominal do Título (contem 10 dígitos)
Posições 20 a 44 - Campo Livre para uso dos bancos (contem 25 dígitos)

NOTA: As posições 20 a 44, por serem de uso dos bancos, é calculado pela classe (child) que implementa o banco. Veja "5. IMPLEMENTANDO NOVOS BANCOS" para mais detalhes.

output - Contém todos os valores que serão impressos nos campos do boleto.

NOTA: Esta propriedade so é populada quando o método output() é explicitamente chamado. Veja "INSTALAÇÃO (Integrar o API)" acima.

5. IMPLEMENTANDO NOVOS BANCOS

A classe principal desta biblioteca chama-se Boleto localizada em ../boleto-lib/Boleto.class.php e é a responsavel pelogerenciamento da sub classe (child) que implementa o banco e também responsavel pelos cálculos que geram os valoresprontos a serem impressos no boleto.

As classes children que implementam caracteristicas específicas de cada banco devem obedecer a este padrãode nome e localização:

../boleto-lib/XXX/Banco_XXX.php

Onde XXX é o código do banco com 3 dígitos.

Na pasta ../boleto-lib/XXX, além do arquivo Banco_XXX.php, deverá conter também:

(obrigatório) logo.jpg - A logomarca do banco

(obrigatório) readme.txt - Instruções específica do banco sendo implementado que fogem a regra geral.

(opcional) layout.tpl.php - Se este arquivo existir então o API desconsiderara o template padrão, que é ../boleto-lib/boleto.tpl.php e usará o layout definido pela implementação do banco.

Dê uma olhada na implementação do Banco do Brasil para ver um exemplo disto na prática.

(opcional) style.css - Mesmo caso do layout.tpl.php. Se este arquivo existir ele será usado ao invés do style padrão, que é ../boleto-lib/style.css. O Banco do Brasil é um bom exemplo.

Uma vez que você criar o arquivo Banco_XXX.php você deverá proceder da seguinte forma:(dê uma olhada nos implementações já existentes para ver na prática)

<?php

//O nome da classe child deverá ter o mesmo nome do arquivo.

//Substitua XXX pelo código do banco

class Banco_XXX extends Boleto{

/**IMPORTANTE: Nunca sobrescreva qualquer valor da propriedade $this->arguments Ao invés disto salve resultados em $this->computed['..nome do campo ..'] */

//Este metodo e' obrigatorio

function setUp(){

//Este método "setUp()" é chamado logo no comeco da criação do objeto.

//Aqui você tem a chance de configurar informações da biblioteca, como o nome do banco por exemplo.

....Seu código vai aqui.....

//Para imprimir na tela todas as propriedades do objeto disponiveis:

echo '<pre>';

print_r($this);

}

//Este método é obrigatório

function febraban_20to44(){

//Para imprimir na tela todas as propriedades do objeto disponiveis:

echo '<pre>';

print_r($this);

//aqui será onde você deverá construir os 25 dígitos que fazem parte do

//campo livre de uso do banco

....Seu código vai aqui ....

//no final salve o seu valor na propriedade febraban, assim:

$this->febraban['20-44'] = $meu_valor_com_25_dígitos;

}

//Este método é opcional

function custom(){

//Este é o ultimo método chamado pelo construtor e aqui você tem a chance de fazer os retoques finais

//no objeto caso seja necessário

...Seu código vai aqui ....

}

//Este método também é opcional e não é chamado pelo construtor, ou seja,

//ele so é chamado depois que o método output() é explicitamente chamado.

//Veja "INSTALAÇÃO (Integrar o API)".

function outputValues(){

//aqui você terá a chance de modificar ou incluir campos na propriedade

//"output" do objeto.

...Seu código vai aqui ....

}

//Parabéns você acabou de implementar um novo banco

}

?>


6. DEBUGGING

Independente se você esta tentando integrar o API à sua aplicação ou desenvolvendo uma implementação para um determinado banco, as vezes as coisas podem não funcionar como o esperado.

Assim fique sempre de olho na propriedade do objeto chamada "warnings", pois se houver alguma mensagem la(que não quer dizer necessáriamente que algo esta errado, por isso chama-se warnings) esta poderá te dar umapista do que esta causando o resultado indesejado.

7. PUBLICANDO A SUA IMPLEMENTAÇÃO

NOTA:
Os releases de implementações precisam ser sob a versão versão 2 or higher da GNU General Public License

Uma vez que sua nova implementação estiver pronta, você pode publica-la de duas formas:

Opção: CRIAR SEU PROPRIO REPOSITORIO NO GITHUB.COM OU QUALQUER OUTRO SERVICO DE SUA ESCOLHA (Precisa ter conhecimentos em Git http://pt.wikipedia.org/wiki/Git)

a) Crie uma conta no github.com (ou outro serviço que lhe agrade. Hospedagem é gratuita para projetos Open Source), caso já não tenha uma, e crie um repositório chamado Boleto-Nome do Banco

b) Faça os commits e pushes necessários para publicar no repositório.

c) Crie uma Wiki no repositório seguindo o padrão dos bancos já implementados. Veja a pagina Wiki da Caixa por exemplo em https://github.com/drupalista-br/Boleto-Caixa/wiki/Projeto-Boletophp-API-|-Caixa-Econômica-Federal

d) Abra um novo Issue em https://github.com/drupalista-br/Boleto/issues e poste o link da pagina Wiki que você criou.

Após a sua implementação for testada e aprovada, o seu link será adicionada a lista de Implementações da pagina da biblioteca principal em https://github.com/drupalista-br/Boleto/wiki/Projeto-Boletophp-API.


Opção: USAR A CONTA DO DRUPALISTA-BR NO GITHUB.COM

a) Compacte os arquivos de sua implementação e coloque em qualquer lugar na internet onde possa ser baixado.

b) Abra um novo Issue em https://github.com/drupalista-br/Boleto/issues e poste o link para que possa ser baixado e testado.

c) Uma vez aprovado eu criarei um novo repositório na conta do drupalista-br onde a sua implementação será publicada. Sera dado os devidos creditos a sua autoria, mas o release tem que ser sob a versão 2 or higher da GNU General Public License.

NOTA:
Caso você deseje, poder de administrador poderá ser dada a você para administrar o repositório de sua implementação.

Entretanto é imprecindivel que você saiba usar a ferramenta git. Informações sobre o git em http://pt.wikipedia.org/wiki/Git

Sim, o git pode ser usado no Windows, antes que você pergunte. Entretanto peço gentilmente que não poste perguntas sobre o git na lista de Issues pois existem varios lugares mais apropriados na internet que melhor podem sanar suas dúvidas a respeito do assunto.