# Resumo

## Introdução

`Zend_Search_Lucene` é um mecanismo para pesquisa de texto, de propósito geral, escrito totalmente em PHP 5. Por armazenar os índices no sistema de arquivos e não fazer uso de servidor de banco de dados, ele pode efetuar pesquisas em qualquer website rodando PHP. O `Zend_Search_Lucene` possui os seguintes recursos:

- Pesquisa agrupada por pontuação (ranked) - os resultados mais prováveis são retornados primeiro

- Consultas poderosas de diversos tipos: frase, curingas, booleanas, aproximação, faixas e muitas outras.

- Busca por campo específico (ex: título, autor, descrição)

`Zend_Search_Lucene` derivou do projeto Apache Lucene. Atualmente (iniciando do ZF 1.6), as versões suportadas formato de índice Lucene são 1.4 - 2.3. Para mais informações, visite .

###

Implementações anteriores de `Zend_Search_Lucene` suportam os formatos de índice Lucene 1.4 (1.9) - 2.1.

A partir do Zend Framework 1.5, qualquer índice criado usando formato de índice menor que 2.1 é atualizado automaticamente para o formato Lucene 2.1 após a atualização `Zend_Search_Lucene` e não será compatível com as implementações do `Zend_Search_Lucene` incluídas no Zend Framework 1.0.x.

## Objetos Documento e Campo

`Zend_Search_Lucene` trabalha sobre os documentos subdividindo-os em pequenos objetos (atômicos) de indexação. Um documento é dividido em campos identificados cujo conteúdo é pesquisado.

Um documento é representado pela classe `Zend_Search_Lucene_Document`, e os objetos dessa classe contêm instâncias de `Zend_Search_Lucene_Field` que representam os campos no documento.

O que é importante ressaltar é que qualquer informação pode ser adicionada a um índice. Informações específicas de aplicações ou metadados podem ser armazenados em campos de um documento, e posteriormente recuperados juntamente com o documento durante uma pesquisa.

Controlar o indexador é responsabilidade de sua aplicação. Este recurso garante que os dados possam ser indexados a partir de qualquer fonte que seja acessível à sua aplicação. Por exemplo, um sistema de arquivos, um banco de dados, um formulário HTML, etc.

A classe `Zend_Search_Lucene_Field` provê alguns métodos estáticos para criação de campos com diferentes características:

    $doc = new Zend_Search_Lucene_Document();

    // O campo não é marcado, mas é indexado e armazenado dentro do índice.
    // Campos armazenados podem ser recuperados a partir do índice.
    $doc->addField(Zend_Search_Lucene_Field::Keyword('doctype',
                                                     'autogenerated'));

    // O campo não é marcado nem indexado, mas é armazenado no índice.
    $doc->addField(Zend_Search_Lucene_Field::UnIndexed('created',
                                                       time()));

    // O campo avaliado como string binária não é marcado nem indexado,
    // mas é armazenado no índice.
    $doc->addField(Zend_Search_Lucene_Field::Binary('icon',
                                                    $iconData));

    // O campo é marcado e indexado, e é armazenado no índice.
    $doc->addField(Zend_Search_Lucene_Field::Text('annotation',
                                                  'Document annotation text'));

    // O campo é marcado e indexado, mas não é armazenado no índice.
    $doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                      'My document content'));

Cada um desses métodos (excluindo o método `Zend_Search_Lucene_Field::Binary()`) têm um parâmetro `$encoding` opcional para especificar a entrada dos dados de codificação.

A codificação pode divergir entre documentos diferentes, bem como para campos diferentes dentro de um mesmo documento:

    $doc = new Zend_Search_Lucene_Document();
    $doc->addField(Zend_Search_Lucene_Field::Text('title',
                                                  $title,
                                                  'iso-8859-1'));
    $doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                      $contents,
                                                      'utf-8'));

Se o parâmetro de codificação é omitido, então a localidade atual é usada em tempo de processamento. Por exemplo:

    setlocale(LC_ALL, 'de_DE.iso-8859-1');
    ...
    $doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $contents));

Os campos são sempre armazenados e devolvidos ao índice na codificação UTF-8. Qualquer conversão necessária para UTF-8 acontece automaticamente.

Analisadores de texto (veja abaixo) também podem converter texto para algumas outras codificações. Na verdade, o analisador de padrão converte o texto para a codificação 'ASCII//TRANSLIT'. Porém, tenha cuidado, esta tradução pode depender da localidade atual.

Nomes de campos são definidos a seu critério no método `addField()`.

Java Lucene usa o campo 'contents' como um campo padrão de busca. `Zend_Search_Lucene` busca por padrão através de todos os domínios, mas este comportamento é configurável. Consulte o capítulo "Campo de pesquisa padrão" para mais detalhes.

## Entendendo os Tipos de Campos

- Campos do tipo `Keyword` são armazenados e indexados, o que significa que eles podem ser pesquisados, bem como apresentados nos resultados de busca. Eles não podem ser divididos em palavras separadas por marcação. Campos de dados numerados geralmente os traduzem bem no `Zend_Search_Lucene`.

- Campos do tipo `UnIndexed` não são pesquisáveis, mas são retornados junto com os resultados das pesquisas. Timestamps de banco de dados, chaves primárias, caminhos do sistema de arquivos, e outros identificadores externos são bons candidatos para estes campos.

- Campos do tipo `Binary` não são avaliados nem indexados, mas são armazenados para serem retornados em resultados de pesquisas. Eles podem ser usados para armazenar qualquer tipo de dado que possa ser codificados em uma string binária, por exemplo, um ícone.

- Campos do tipo `Text` são armazenados, indexados e avaliados. Campos texto são apropriados para conter informações que devam ser pesquisadas, bem como retornadas por uma pesquisa, tais como descrições e títulos.

- Campos do tipo `UnStored` são avaliados e indexados, mas não são armazenados no índice. Grandes quantidades de texto são melhor indexadas utilizando este tipo de campo. Dados armazenados criam um extenso índice no disco, então se você necessitar pesquisar sem exibir estes dados, utilize um campo UnStored. Campos UnStored são úteis quando utilizamos um índice `Zend_Search_Lucene` em combinação com um banco de dados relacional. Você pode indexar campos contendo dados volumosos usando campos UnStored para pesquisa, e recuperá-los a partir de um banco de dados relacional usando campos separados como identificadores.

  ### Tipos de Zend_Search_Lucene_Field

  Tipo de Campo | Armazenado | Indexado | Marcado | Binário
  --- | --- | --- | --- | ---
  Keyword | Sim | Sim | Não | Não
  UnIndexed | Sim | Não | Não | Não
  Binary | Sim | Não | Não | Sim
  Text | Sim | Sim | Sim | Não
  UnStored | Não | Sim | Sim | Não

## Documentos HTML

`Zend_Search_Lucene` oferece um recurso para análise de HTML. Os documentos podem ser criados diretamente a partir de um arquivo ou string HTML:

    $doc = Zend_Search_Lucene_Document_Html::loadHTMLFile($filename);
    $index->addDocument($doc);
    ...
    $doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
    $index->addDocument($doc);

A classe `Zend_Search_Lucene_Document_Html` utiliza os métodos `DOMDocument::loadHTML()` e `DOMDocument::loadHTMLFile()` para analisar o código HTML, por isso não precisa de HTML bem formatado ou de XHTML. Por outro lado, é dependente da codificação especificada pela tag de cabeçalho "meta http-equiv".

A classe `Zend_Search_Lucene_Document_Html` reconhece o título do documento, o corpo e as meta tags do cabeçalho.

O campo 'title' é na verdade o valor /html/head/title. É armazenado no índice, marcado e disponibilizado para pesquisa.

O campo 'body' é o próprio conteúdo corpo do arquivo ou string HTML. Não inclui os scripts, comentários ou atributos.

Os métodos `loadHTML()` e `loadHTMLFile()` da classe `Zend_Search_Lucene_Document_Html` também possuem um segundo argumento opcional. Se for definido como `TRUE`, o conteúdo do corpo é também armazenado no índice e pode ser recuperado a partir do índice. Por padrão, o corpo é marcado e indexado, mas não armazenado.

O terceiro parâmetro dos métodos `loadHTML()` e `loadHTMLFile()` especifica opcionalmente a codificação do código no documento HTML. É utilizado quando a codificação não é especificada usando a meta tag Content-type HTTP-EQUIV.

Outras meta tags do cabeçalho no documento produzem campos de documentos adicionais. O campo 'name' é tirado do atributo 'name', e o atributo o 'content' preenche o campo 'value'. Ambos são marcados, indexados e armazenados, então os documentos podem ser procurados pelas suas meta tags (por exemplo, por palavras-chave).

Qualquer outro campo pode ser acrescentado pelo programador em documentos analisados:

    $doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
    $doc->addField(Zend_Search_Lucene_Field::UnIndexed('created',
                                                       time()));
    $doc->addField(Zend_Search_Lucene_Field::UnIndexed('updated',
                                                       time()));
    $doc->addField(Zend_Search_Lucene_Field::Text('annotation',
                                                  'Document annotation text'));
    $index->addDocument($doc);

Links nos documentos não estão incluídos no documento gerado, mas podem ser recuperados através dos métodos `Zend_Search_Lucene_Document_Html::getLinks()` e `Zend_Search_Lucene_Document_Html::getHeaderLinks()`:

    $doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
    $linksArray = $doc->getLinks();
    $headerLinksArray = $doc->getHeaderLinks();

A partir do Zend Framework 1.6 é possível excluir os links com o atributo `rel` definido como `'nofollow'`. Utilize `Zend_Search_Lucene_Document_Html::setExcludeNoFollowLinks($true)` para ativar esta opção.

O método `Zend_Search_Lucene_Document_Html::getExcludeNoFollowLinks()` retorna o estado atual do marco "Exclude nofollow links".

## Documentos do Word 2007

`Zend_Search_Lucene` oferece um recurso de análise para Word 2007. Os documentos podem ser criados diretamente de um arquivo do Word 2007:

    $doc = Zend_Search_Lucene_Document_Docx::loadDocxFile($filename);
    $index->addDocument($doc);

A classe `Zend_Search_Lucene_Document_Docx` utiliza a classe `ZipArchive` e os métodos `simplexml` para analisar o documento de origem. Se a classe `ZipArchive` (do módulo php_zip) não estiver disponível, o `Zend_Search_Lucene_Document_Docx` também não estará disponível para ser usado com o Zend Framework.

A classe `Zend_Search_Lucene_Document_Docx` reconhece os metadados e o texto do documento. Metadados consiste, dependendo do conteúdo do documento, de nome do arquivo (filename), título (title), assunto (subject), autor (creator), palavras-chave (keywords), descrição (description), última modificação por (lastModifiedBy), revisão (revision), data da modificação (modified) e data da criação (created).

O campo 'filename' é o nome do arquivo do Word 2007.

O campo 'title' é o título do documento.

O campo 'subject' é o assunto do documento.

O campo 'creator' é o autor do documento.

O campo 'keywords' contém as palavras-chaves do documento.

O campo 'description' é a descrição do documento.

O campo 'lastModifiedBy' é o nome de quem fez a última modificação no documento.

O campo 'revision' é o número da revisão do documento.

O campo 'modified' contém a data e hora da última modificação do documento.

O campo 'created' contém a data e hora da criação do documento.

O campo 'body' é o próprio conteúdo do documento do Word 2007. Ele inclui apenas texto normal, comentários e revisões não estão incluídos.

O método `loadDocxFile()` da classe `Zend_Search_Lucene_Document_Docx` também possui um segundo argumento opcional. Se for definido como `TRUE`, o conteúdo do corpo é também armazenado no índice e pode ser recuperado a partir do índice. Por padrão, o corpo é marcado e indexado, mas não armazenado.

Qualquer outro campo pode ser acrescentado pelo programador em documentos analisados:

    $doc = Zend_Search_Lucene_Document_Docx::loadDocxFile($filename);
    $doc->addField(Zend_Search_Lucene_Field::UnIndexed(
        'indexTime',
        time())
    );
    $doc->addField(Zend_Search_Lucene_Field::Text(
        'annotation',
        'Document annotation text')
    );
    $index->addDocument($doc);

## Documentos do Powerpoint 2007

`Zend_Search_Lucene` oferece um recurso de análise para Powerpoint 2007. Os documentos podem ser criados diretamente de um arquivo do Powerpoint 2007:

    $doc = Zend_Search_Lucene_Document_Pptx::loadPptxFile($filename);
    $index->addDocument($doc);

A classe `Zend_Search_Lucene_Document_Pptx` utiliza a classe `ZipArchive` e os métodos `simplexml` para analisar o documento de origem. Se a classe `ZipArchive` (do módulo php_zip) não estiver disponível, o `Zend_Search_Lucene_Document_Pptx` também não estará disponível para ser usado com o Zend Framework.

A classe `Zend_Search_Lucene_Document_Pptx` reconhece os metadados e o texto do documento. Metadados consiste, dependendo do conteúdo do documento, de nome do arquivo (filename), título (title), assunto (subject), autor (creator), palavras-chave (keywords), descrição (description), última modificação por (lastModifiedBy), revisão (revision), data da modificação (modified) e data da criação (created).

O campo 'filename' é o nome do arquivo do Powerpoint 2007.

O campo 'title' é o título do documento.

O campo 'subject' é o assunto do documento.

O campo 'creator' é o autor do documento.

O campo 'keywords' contém as palavras-chaves do documento.

O campo 'description' é a descrição do documento.

O campo 'lastModifiedBy' é o nome de quem fez a última modificação no documento.

O campo 'revision' é o número da revisão do documento.

O campo 'modified' contém a data e hora da última modificação do documento.

O campo 'created' contém a data e hora da criação do documento.

O campo 'body' é o conteúdo de todos os slides e notas de slide no documento do Powerpoint 2007.

O método `loadPptxFile()` da classe `Zend_Search_Lucene_Document_Pptx` também possui um segundo argumento opcional. Se for definido como `TRUE`, o conteúdo do corpo é também armazenado no índice e pode ser recuperado a partir do índice. Por padrão, o corpo é marcado e indexado, mas não armazenado.

Qualquer outro campo pode ser acrescentado pelo programador em documentos analisados:

    $doc = Zend_Search_Lucene_Document_Pptx::loadPptxFile($filename);
    $doc->addField(Zend_Search_Lucene_Field::UnIndexed(
        'indexTime',
        time()));
    $doc->addField(Zend_Search_Lucene_Field::Text(
        'annotation',
        'Document annotation text'));
    $index->addDocument($doc);

## Documentos do Excel 2007

`Zend_Search_Lucene` oferece um recurso de análise para Excel 2007. Os documentos podem ser criados diretamente de um arquivo do Excel 2007:

    $doc = Zend_Search_Lucene_Document_Xlsx::loadXlsxFile($filename);
    $index->addDocument($doc);

A classe `Zend_Search_Lucene_Document_Xlsx` utiliza a classe `ZipArchive` e os métodos `simplexml` para analisar o documento de origem. Se a classe `ZipArchive` (do módulo php_zip) não estiver disponível, o `Zend_Search_Lucene_Document_Xlsx` também não estará disponível para ser usado com o Zend Framework.

A classe `Zend_Search_Lucene_Document_Xlsx` reconhece os metadados e o texto do documento. Metadados consiste, dependendo do conteúdo do documento, de nome do arquivo (filename), título (title), assunto (subject), autor (creator), palavras-chave (keywords), descrição (description), última modificação por (lastModifiedBy), revisão (revision), data da modificação (modified) e data da criação (created).

O campo 'filename' é o nome do arquivo do Excel 2007.

O campo 'title' é o título do documento.

O campo 'subject' é o assunto do documento.

O campo 'creator' é o autor do documento.

O campo 'keywords' contém as palavras-chaves do documento.

O campo 'description' é a descrição do documento.

O campo 'lastModifiedBy' é o nome de quem fez a última modificação no documento.

O campo 'revision' é o número da revisão do documento.

O campo 'modified' contém a data e hora da última modificação do documento.

O campo 'created' contém a data e hora da criação do documento.

O campo 'body' é o conteúdo de todas as células em todas as planilhas do documento do Excel 2007.

O método `loadXlsxFile()` da classe `Zend_Search_Lucene_Document_Xlsx` também possui um segundo argumento opcional. Se for definido como `TRUE`, o conteúdo do corpo é também armazenado no índice e pode ser recuperado a partir do índice. Por padrão, o corpo é marcado e indexado, mas não armazenado.

Qualquer outro campo pode ser acrescentado pelo programador em documentos analisados:

    $doc = Zend_Search_Lucene_Document_Xlsx::loadXlsxFile($filename);
    $doc->addField(Zend_Search_Lucene_Field::UnIndexed(
        'indexTime',
        time()));
    $doc->addField(Zend_Search_Lucene_Field::Text(
        'annotation',
        'Document annotation text'));
    $index->addDocument($doc);