Documentação

TxtXtrator

Classe para extração de dados de arquivos texto.


Conteúdo

  1. Overview
  2. Exemplo básico
  3. Template
  4. Opções de configuração
  5. Métodos
  6. Arquivos
  7. Mais informações
  8. Licenciamento

Voltar ao conteúdo

Overview

TxtXtrator é uma classe PHP que oferece ferramentas para extração, tratamento e conversão de arquivos texto com dados no formato de colunas com largura fixa, CSV (texto separados por vírgula ou ponto-e-vírgula) ou relatórios em modo texto.

Os dados extraídos com TxtXtrator podem ser transformados em Array PHP, JSON, CSV, SQL ou tabela HTML.

Os dados convertidos podem ser simplismente retornados pela classe, exibidos no browser ou salvos em arquivos, diretamente no HD ou disponibilizado para download.


Voltar ao conteúdo

Exemplo

Arquivo exemplo.php

          loadFile($filename);//"Lê" o arquivo para $TxtXtrator
            $TxtXtrator->loadTpl('C:/Users/Everton/Documents/My Dropbox/projects/txt-xtrator/credorsmall.json');//carrega o template
            $TxtXtrator->setCsvSeparator(';');//define o separador de colunas para dados CSV
            $TxtXtrator->xtract();//extrai os dados
            $TxtXtrator->setOutputType('sql');//define o tipo de saída
            $TxtXtrator->setLineBreakType('windows');//define o tipo de quebra de linha
            $TxtXtrator->output();//transforma os dados extraídos no formato de saída configurado por setOutputType()
            $TxtXtrator->show();//exibe os dados transformados no browser
            $TxtXtrator->export();//exporta os dados de forma a serem salvos em arquivo
            $TxtXtrator->download();//realiza o download dos dados em arquivo
            $TxtXtrator->file('C:/Users/Everton/Documents/My Dropbox/projects/txt-xtrator/teste.txt');//salva os dados diretamente em arquivo
          ?>
      

Arquivo template.json

      {
        "firstRow":0//define a linha pela qual se iniciará a importação
        ,"rowLen":236//define o tamanho da linha para arquivos-fonte com largura fixa
        ,"fileType":"fixed"//define o tipo de arquivo-fonte
        ,"sqlTable":"credores"//nome da tabela para outputType = sql
        ,"cm":[//define o modelo de coluna (col model)
                {
                    "ref":"cod"//referência da coluna (obrigatório)
                    ,"start":0//caractere de início da coluna (obrigatório)
                    ,"len":10//tamanho em caracteres da coluna (obrigatório)
                    ,"sqlName":"id"//nome de coluna a ser utilizado com SQL
                },{
                    "ref":"nome"
                    ,"start":10
                    ,"len":60
                    ,"fn":"noSpace"//função a ser acionada para tratar os dados
                },{
                    "ref":"cpfcnpj"
                    ,"start":70
                    ,"len":14
                },{
                    "ref":"cgcte"
                    ,"start":84
                    ,"len":15
                },{
                    "ref":"endereco"
                    ,"start":114
                    ,"len":50
                    ,"fn":"noSpace"
                },{
                    "ref":"cidade"
                    ,"start":164
                    ,"len":30
                    ,"fn":"noSpace"
                },{
                    "ref":"uf"
                    ,"start":194
                    ,"len":2
                },{
                    "ref":"cep"
                    ,"start":196
                    ,"len":8
                },{
                    "ref":"fone"
                    ,"start":204
                    ,"len":15
                },{
                    "ref":"fax"
                    ,"start":219
                    ,"len":15
                },{
                    "ref":"tipo"
                    ,"start":234
                    ,"len":2
                }
            ]
        }
      

Voltar ao conteúdo

Template

Template é a denominação dada à configuração estruturada do arquivo-fonte de dados que contém parâmetros para a interpretação do arquivo e o modelo de coluna, utilizado para interpretar cada coluna de dados.

A configuração de template deve ser armazenada no formato JSON, em um arquivo texto (sugere-se a extenção .json).

A estrutura do template é a seguinte (com valores de exemplo):

          {
            "firstRow":0
            ,"countRow":100
            ,"rowLen":50
            ,"fileType":"fixed"
            ,"sqlTable":"nome_tabela"
            ,"csvSeparator":";"
            ,"cm":[
                {
                    "ref":"campo1"
                    ,"start":0
                    ,"len":5
                    ,"sqlName":"campo_1"
                    ,"fn":"nomeFuncao1"
                },{
                    "ref":"campo2"
                    ,"start":5
                    ,"len":10
                    ,"sqlName":"campo_2"
                    ,"fn":"nomeFuncao2"
                }
            ]
          }
      

Opçoes de configuração

integer firstRow
(Opcional) Indica a partir de qual linha do arquivo-fonte os dados começarão a serem importados. O valor padrão é 0 (zero), equivalente à primeira linha.
integer rowLen
(Obrigatório se filetype = 'fixed') Indica o tamanho, em caracteres, de cada linha para que ela seja importada. Linhas com tamanho menor ou maior que o definido em rowLen serão ignoradas. rowLen somente é válido se fileType for igual a 'fixed'.
string fileType
(Obrigatório) Indica o tipo de arquivo-fonte que será processado. Admite 'fixed' para arquivos texto com largura fixa (e ralatórios mal-formatados) e 'csv' para arquivos CSV.
string sqlTable
(Obrigatório se outputType = 'sql') Indica o nome de tabela para ser utilizado em saídas SQL.
string csvSeparator
(Obrigatório se outputType = 'csv' ou fileType = 'csv') Indica o caractere que será utilizado como separador de campos quando outputType = 'csv' ou fileType = 'csv'.
integer countRow
(Opcional) Indica a quantidade de linhas que serão lidas no arquivo-fonte para importação. Útil para não importar todos os registros ou para implementar algum tipo de paginação, por exemplo.
array cm
(Obrigatório) Armazena a configuração das colunas (colummn model).
string ref
(Obrigatório) Indica o nome da coluna.
integer start
(Obrigatório se fileType = 'fixed') Indica o caractere de início da coluna (o primeiro caractere de cada linha é 0 (zero).
integer len
(Obrigatório se fileTupe = 'fixed') Indica o tamanho da coluna em caracteres.
string sqlName
(Opcional) Indica o nome da coluna para outputType = 'sql'. Se ausente ref será usado.
string fn
(Opcional) Indica o nome de uma função que será chamada para tratar os dados da coluna. Essa função recebe o valor da intersecção LinhaxColuna (célula) e deve retornar o valor a ser armazenado an intersecção.

Voltar ao conteúdo

Opções de configuração

Ao instanciar a classe TxtXtrator(), é possível configurar algumas de suas propriedades através de um array.

Tenha em mente que qualquer configuração feita desta forma será sobreescrita ao carregar um template.

Opções disponíveis

Descrição das opções de configuração

outputType
Indica o tipo de saída para os dados extraídos. Aceita os valores array, json, csv, sql e html.
firstRow
Veja firstRow nas configurações de Template.
countRow
Veja countRow nas configurações de Template.
rowLen
Veja rowLen nas configurações de Template.
fileType
Veja fileType nas configurações de Template.
csvSeparator
Veja csvSeparator nas configurações de Template.
lineBreakType
Indica o tipo de quebra de linha a ser utilizada. Aceita os valores linux, windows e html.
sqlTable
Veja sqlTable nas configurações de Template.

Voltar ao conteúdo

Métodos públicos

__construct(array $config)
Construtor da classe. Recebe em $config um array com configurações. Retorna void.
loadFile(string $filename)
Lê o conteúdo do arquivo passado por $file, retornando true no caso de sucesso e false no caso de falha.
loadTpl(string $tpl)
Lê o conteúdo do arquivo de Template passado por $tpl e retorna true ou false em caso de sucesso ou falha.
xtract()
Extrai os dados do arquivo carregado por loadFile() de acordo com o template. Retorna true ou false, caso sucesso ou falha.
output()
Formata os dados extraídos para um dos formatos de saída, conforme definido na propriedade outputType. Retorna true ou false, conforme haja sucesso ou falha.
getLastError()
Retorna um array contendo o último erro registrado no log de erros.
getErrors()
Retorna o log de erros compelto, no formato de um array.
get()
Retorna um array com as linhas dos dados formatados de acordo com outputType.
show()
Exibe no brouxer os dados formatados conforme outputType. Retorna true ou false, se sucesso ou falha.
download()
Disponibiliza o download de um arquivo contendo os dados formatados, desde que outputType seja json, csv, sql ou html. Deve ser chamado antes de qualquer comando echo do PHP ou qualquer envio de conteúdo para o browser. Esta função é influenciada por lineBreakType. Retorna true ou false.
file(string $filename)
Escreve os dados formatados conforme outputType desde que outputType seja diferente de array ou html. Os dados são escritos no arquivo passado em $filename. Esta função é influenciada por lineBreakType. Retorna true ou false.
Métodos set
Os métodos set são funções para atribuir valor às propriedades da classe.
Métodos get
Os métodos get são funções para retornar o valor das propriedades da classe.

Voltar ao conteúdo

Arquivos da classe

a classe TxtXtract() possui um único arquivo chamado TxtXtrator.class.php que pode ser utilizado através de include() ou require() ou ainda require_once() ou include_once().

além disso, o diretório "examples" contém exemplos de utilização.


Voltar ao conteúdo

Mais informações

Mais informações, críticas ou sugestões, além de aprimoramentos podem ser conseguidos com o desenvolvedor através do email everton3x@gmail.com


Voltar ao conteúdo

Licença

TxtXtract é distribuído sob a GPL, cuja cópia está no arquivo gpl-3.0.txt.