@author Francisco Luz <franciscoferreiraluz at yahoo dot com dot au>
@package Boleto
@version 1.0 Beta

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 arquivo
   de 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:

   a) Copie a pasta boleto-lib para um diretorio dentro de sua pasta pública.
      Por exemplo: www/bibliotecas/boleto-lib
 
   b) 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.

   c) 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

   d) 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

      NOTAS: 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" para desenvolver o seu próprio
             plugin, uma vez que tiver pronto disponibilize o código para que este possa ser
             publicado no projeto.
             
   d) 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.

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

        Leia o arquivo readme.txt da implementação de cada banco localizado em
        www/bibliotecas/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-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);

        visite 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 envie
   emails 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ções
   de 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:

     1o. 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 ;)

     2o. 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 quando
   estiverem 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 as
   instruções, tais como este readme, antes de abrir um novo Issue, pois na maioria dos casos a pergunda
   já 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 "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 pelo
   gerenciamento da sub classe (child) que implementa o banco e também responsavel pelos cálculos que geram os valores
   prontos a serem impressos no boleto.

   As classes children que implementam caracteristicas específicas de cada banco devem obedecer a este padrão
   de 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 método é obrigatório
       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 uma
   pista 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 2 or higher da GNU General Public License

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

   1a 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.

     b) 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

     c) 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.

   2a 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.

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

      d) 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 alguém 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.