README

此插件允许您在SilverStripe框架中使用Lucene搜索引擎的力量。

使用各种工具，您还可以搜索PDF、Word、Excel、Powerpoint和平文文件。

设置和使用都很容易。

此插件使用Zend_Search_Lucene（来自Zend）、Kenny Katzgrau的StandardAnalyzer以及Joeri Stegeman的pdf-to-text进行PDF扫描。

Zend_Search_Lucene是Apache项目Lucene搜索引擎的PHP端口。

此扩展程序灵感来源于WordPress的wpSearch插件。http://codefury.net/projects/wpSearch/

已修改以适应SilverStripe 3.0.x和3.1

Graeme Smith <gs78 (at) me (dot) com>

####待办事项：测试未通过 - 状态列和临时表错误

维护者联系方式

Darren Inwood <darren (dot) inwood (at) chrometoaster (dot) com>

需求

SilverStripe 3.0或更高版本的'Queued Jobs'模块 - 查看：https://github.com/nyeholt/silverstripe-queuedjobs

此模块目前在LAMP上进行了测试 - Windows和Mac OS X应该也可以工作，但尚未测试。

文档

http://code.google.com/p/lucene-silverstripe-plugin/

在docs目录中还有生成的phpdoc文档。

安装说明

将存档检出到您项目的根目录。这应该是与'framework'目录相同的文件夹。

通过Git：git submodule add https://github.com/Instagraeme/silverstripe-lucene lucene

这将在包含插件文件的'lucene'目录中创建一个目录。

要使用Lucene，您需要安装'Queued Jobs'模块。

通过Git：git submodule add https://github.com/nyeholt/silverstripe-queuedjobs queuedjobs

要使队列作业运行，您还需要在_ssilverstripe_environment.php文件中添加$_FILE_TO_URL_MAPPING，如SilverStripe文档中所述

http://doc.silverstripe.org/sapphire/en/topics/commandline

运行 /dev/build?flush=1 以通知SilverStripe关于您的新模块，并且您的搜索引擎已安装！（您仍需要启用它 - 下面说明。）

第三方实用程序安装

要启用Linux上使用pdftotext实用程序进行PDF扫描，请确保已安装命令行实用程序。如果您使用Debian或Ubuntu，poppler-utils或xpdf-utils包之一将提供此实用程序

apt-get install poppler-utils

如果您使用其他Linux、Mac OS X或Windows，Xpdf程序包含pdftotext

http://www.foolabs.com/xpdf/

如果您未安装pdftotext实用程序，Lucene将使用Joeri Stegeman的基于PHP的PDF2Text类。然而，与pdftotext相比，此类的功能有限。

Word、Excel和Powerpoint扫描都需要安装'zip' PHP模块。如果您没有安装它，则无法扫描新的docx、xlsx和pptx文档。

为了使扫描旧版doc、xls和ppt文档正常工作，您需要安装catdoc命令行实用程序。也有Windows和Mac OS X的端口。

http://wagner.pp.ru/~vitus/software/catdoc/ http://blog.brush.co.nz/2009/09/catdoc-windows/ http://catdoc.darwinports.com/

快速入门

如果您只想尽快启动 Lucene 搜索引擎，请按照上述说明进行安装，然后向您的项目 _config.php 文件中添加以下行

ZendSearchLuceneSearchable::enable();

如果您使用的是 Black Candy 主题或支持标准 SilverStripe 全文搜索的其他主题，您的搜索现在将使用 Lucene 运行，索引所有页面和可索引文件（PDF、Word、Excel、Powerpoint 和 HTML）。

要充分利用您的新搜索引擎，请继续阅读。

配置说明

启用搜索引擎

默认情况下，Lucene 搜索引擎未启用。要启用它，您需要在 _config.php 文件中添加以下内容

ZendSearchLuceneSearchable::enable();

这将通过向这些类添加 'ZendSearchLuceneSearchable' 扩展来配置所有 SiteTree 和 File 对象。以下字段将在写入数据库的此类对象时进行索引

'SiteTree' => 'Title,MenuTitle,Content,MetaTitle,MetaDescription,MetaKeywords', 'File' => 'Filename,Title,Content'

启用搜索引擎后，您需要首次构建索引。在 SiteConfig 页面上有一个新的按钮，标记为 '重建搜索索引'，这是位于顶部左侧列中的页面，页面名称为网站名称。这将向 '作业' 列表中添加一个新的作业 - 这将向您显示您的网站重新索引的进度。

如果您只想尽快启动 Lucene，可以跳到下面的 '使用概述' 部分 - 这就是您需要做的所有配置！

索引类

如果您想启用搜索引擎，但不想自动将扩展添加到 SiteTree 和/或 File，请传入一个包含要索引的类的数组：（此选项只接受 SiteTree 和 File，有关其他类的索引，请参阅以下内容）

// 使用以下行之一来控制要扩展的类 ZendSearchLuceneSearchable::enable(array('SiteTree', 'File')); ZendSearchLuceneSearchable::enable(array('SiteTree')); ZendSearchLuceneSearchable::enable(array('File'));

// 不要自动将扩展添加到任何类中 ZendSearchLuceneSearchable::enable(array());

为了索引除了默认以外的类，您需要添加一个包含要索引的字段列表的 ZendSearchLuceneSearchable 扩展。

例如，要索引您的自定义 Page 类，该类添加了自定义的 Summary 和 Intro 字段

Object::add_extension( 'Page', "ZendSearchLuceneSearchable('" ."Title,MenuTitle,MetaTitle,MetaDescription,MetaKeywords," ."Summary,Intro,Content')" );

您还可以索引返回字符串的自定义函数。如果您的索引对象有一个名为 'getFoo()' 的方法，它返回一个表示您想要索引的特殊状态的字符串，将 'getFoo' 添加到字段列表中将会索引此状态。

Lucene 中使用了四种索引类型

1. 关键字 - 可搜索并存储在索引中，但不会分解成标记进行索引的数据。这对于能够搜索非文本数据（如 ID 或 URL）很有用。

2. 未索引 - 不可用于搜索，但与我们的文档一起存储（例如，文章摘要、文章 URL 和创建时间戳）

3. 未存储 - 可用于搜索，但不在索引中完整存储（例如，文档内容）

4. 文本 - 可用于搜索并完整存储在索引中的数据（例如，标题和作者）

MenuTitle、MetaTitle、MetaDescription 和 MetaKeywords 字段将作为未存储索引。LastEdited 和 Created 字段将未索引。ID 和 ClassName 字段将作为关键字类型索引。所有其他字段将作为文本索引。

索引关系

您可以索引 has_one、has_many 和 many_many 关联，使用点符号表示要读取相关对象的字段。

如果我们之间有一个 Page 和自定义类 Foo 的 has_one 关联，并且 Foo 有一个名为 Bar 的文本字段，我们可以在向 Page 类型添加扩展时将其添加到字段列表中

Object::add_extension( 'Page', "ZendSearchLuceneSearchable('" ."Title,MenuTitle,MetaTitle,MetaDescription,MetaKeywords," ."Content,Foo.Bar')" );

如果需要，您可以嵌套多层关联，例如：Foo.Bar.Baz.Buz - 请记住，所使用的名称是关联字段名称，而不是要索引的类名称。

索引文件

当索引 'File' 数据对象时，此模块将使用文件扩展名来检测文件类型。检测到的类型包括 .txt、.xls、.doc、.ppt、.xlsx、.docx、.htm、.html、.pptx 和 .pdf。

有关为各种文件类型启用文件扫描的详细信息，请参阅上述“安装”部分。

高级字段级索引选项

您可以通过添加带有 JSON 编码对象的 ZendSearchLuceneSearchable 扩展来获得对如何索引类的更精细的控制。

您的对象应按键值对排列，键是要索引的属性、方法或关联的名称，值是另一个对象，其中包含表示该字段选项的键值对。

Object::add_extension( 'Page', "ZendSearchLuceneSearchable(' { "Title" : true, "CreatedDate" : { name : "Title", type : "text", content_filter : "strtotime" }, "Intro" : true, "Content" : { name : "Content", type : "unstored" }, "Foo.Bar" : { name : "Baz" }, "Images" : { content_filter : ["HelperClass","countImages"] } } )" );
')" );

省略的任何配置选项将使用默认值。每个字段的可用配置选项包括

• name 将此字段存储为文档中的名称。默认值与字段名称相同。'ID' 的字段名称是一个特殊案例 - 这应始终使用 'ObjectID' 的名称，因为这是内部使用的。

• type 要使用的索引类型。默认值是 "text"，合法选项是 "text"、"keyword"、"unstored" 和 "unindexed"。

• content_filter 在索引之前用于转换字段值的回调。回调将带有一个参数调用，即字段值作为字符串，并且应该返回作为字符串的转换后的字段值。对于将日期字符串转换为 Unix 时间戳之类的用例可能很有用。false 的值将表示不应进行内容过滤，这是默认值。

高级类级索引选项

您还可以在初始化类时使用 Object::add_extension 提供第二个 JSON 编码的参数。它应包含表示您的类级配置的键值对。

Object::add_extension( 'Foo', "ZendSearchLuceneSearchable('Foo,Far,Faz',' { "index_filter" : ""ID" IN ( SELECT "ID" FROM "Foo" LEFT JOIN "Other" ON "Foo"."ID" = "Other"."FooID" WHERE "Other"."FooID" IS NOT NULL )" } ')" );

目前只有一个配置选项

• index_filter 用于在索引此类的项目列表时将字符串用作 DataObject::get() 的第二个参数。默认值是一个空字符串，这将获取该类的所有项目。

请注意，配置可能会因为嵌套转义引号而变得有些混乱。
您可能更喜欢创建 PHP 对象，将其 JSON 编码，然后以这种方式插入

$fields = array( 'Foo' => array( 'name' => 'Foo', ), 'Bar' => array( 'name' => 'Bar', 'type' => 'unstored', 'content_filter' => array('HelperClass','filterFunction') ) ); $class = array( 'index_filter' => ' "ID" IN ( SELECT "ID" FROM "Foo" LEFT JOIN "Other" ON "Foo"."ID" = "Other"."FooID" WHERE "Other"."FooID" IS NOT NULL )' ); Object::add_extension( 'Foo', "'".json_encode($fields)."', '".json_encode($class)."'" );

重建搜索索引

搜索索引在每次 /dev/build 时重建。如果您想禁用此功能，例如如果您的站点相当大且重建搜索索引需要很长时间，您可以将以下内容添加到您的 _config.php 中

ZendSearchLuceneSearchable::$reindexOnDevBuild = false;

要手动重建搜索索引，请访问“网站配置”页面（位于CMS左侧站点树最顶部，带有世界图标），在页面底部将有一个“重建搜索索引”按钮。点击此按钮将启动一个队列任务，该任务将删除当前索引，扫描整个站点以查找所有需要索引的内容，并重新索引所有内容。

您可以在“作业”标签页查看重建索引的进度，位于CMS顶部。它将显示作业开始时间、运行时长、待索引的项目数量以及已索引的项目数量。如果有任何错误，这些也会在这里显示。

分页

有一些分页设置，允许您控制分页功能：（将这些设置放入 _config.php 中进行更改）

// 每页显示的结果数量 ZendSearchLuceneSearchable::$pageLength = 10;

// 分页显示的最大页数 ZendSearchLuceneSearchable::$maxShowPages = 10;

// 总是在分页开始处显示这些页数 ZendSearchLuceneSearchable::$alwaysShowPages = 3;

索引目录

您还可以设置索引的存储位置

// 这些是默认值。ZendSearchLuceneSearchable::$cacheDirectory = TEMP_FOLDER; ZendSearchLuceneWrapper::$indexName = 'Silverstripe';

使用默认设置，索引将创建在 SilverStripe 的临时文件夹中，并命名为 'SilverStripe'。

高级索引配置

http://zendframework.com/manual/en/zend.search.lucene.index-creation.html#zend.search.lucene.index-creation.optimization

您可以直接在索引上使用高级配置功能

$index = ZendSearchLuceneWrapper::getIndex();

// 获取索引大小 $indexSize = $index->count(); $documents = $index->numDocs();

// 索引优化 $index->optimize();

您还可以使用 ZendSearchLuceneWrapper::addCreateIndexCallback() 指定对新创建的索引运行的操作。在创建时，将运行使用此函数注册的任何回调。这允许您在索引上设置所需的任何优化选项。如果没有注册回调，则使用 Zend 默认值。

要使用回调，您可以在 _config.php 中添加如下内容

function create_index_callback() { $index = ZendSeachLuceneWrapper::getIndex(); $index->setMaxBufferedDocs(20); } ZendSearchLuceneWrapper::addCreateIndexCallback('create_index_callback');

使用概述

一旦配置并启用了插件，您可以在模板文件中添加一个新的令牌以输出搜索表单

$ZendSearchLuceneForm

这将提交到 ZendSearchLuceneResults 动作，该动作将显示搜索结果页面。

此模块还将接管 $SearchForm 令牌 - 这是为了方便，以便用户能够快速使用内置主题。如果您打算自定义表单标记，请使用 $ZendSearchLuceneForm。

自定义搜索表单

要自定义搜索表单，请重写此方法（或创建一个新的方法）并输出一个包含名为 'Search' 的字段和动作为 ZendSearchLuceneResults 的表单对象。

/* 自定义搜索表单 */ class Your_Controller extends Page_Controller {

// . . .

function ZendSearchLuceneForm() { $form = parent::ZendSearchLuceneForm(); // 自定义表单 return $form; }

}

如果您在模板中使用 $ZendSearchLuceneForm，您可以为搜索表单创建一个名为 ZendSearchLuceneForm.ss 的自定义模板 - 它可以放在根模板文件夹或 Includes/ 文件夹中。将 sapphire/templates/SearchForm.ss 复制过来是一个很好的起点。

自定义搜索结果页面

在插件的 templates/Layout 文件夹中，您将找到 Lucene_results.ss 文件。将此文件复制到您自己的主题 Layout 文件夹中，并根据需要进行修改。

此文件中可用的模板令牌有

$Query - 搜索字符串 $TotalResults - 搜索结果总数 $TotalPages - 查询的总页数 $ThisPage - 当前查看的页码 $StartResult - 当前页第一项结果的编号 $EndResult - 当前页最后一项结果的编号 $PrevUrl - 上一个搜索结果页面的URL $NextUrl - 下一个搜索结果页面的URL

<% 控制结果 %>

$score (由搜索引擎分配的相关性评分) $Number (此结果在集合中的编号) $Link (此资源的URL) 你还可以使用已索引的任何字段，例如。 $Content <% 结束控制 %>

<% 控制搜索页面 %>

$IsEllipsis (此条目是否为空白省略号以指示更多页面) $PageNumber $Link (此搜索结果页面的URL) $Current (布尔值，指示是否为当前页面) <% 结束控制 %>

一个有用的额外功能是SearchTextHighlight字符串修饰符。如果你在模板中使用例如$Content.SearchTextHighlight，这将输出一个包含你的搜索词周围25个单词的HTML段落，搜索词用标签突出显示。

/**
 * Use $AdvancedSearchForm in your template to output this form.
 */
function AdvancedSearchForm() {
    $fields = new FieldSet(
        new TextField('Query','First search query'),
        new TextField('Subquery', 'Second search query')
    );
    $actions = new FieldSet(
        new FormAction('AdvancedSearchResults', 'Search')
    );
    $form = new Form($this->owner, 'AdvancedSearchForm', $fields, $actions);
    $form->disableSecurityToken();
    return $form;
}

/**
 * Processes the search form
 */
function AdvancedSearchResults($data, $form, $request) {
    // Assemble your custom query 
    $query = Zend_Search_Lucene_Search_QueryParser::parse(
        $form->dataFieldByName('Query')->dataValue()
    );
    $subquery = Zend_Search_Lucene_Search_QueryParser::parse(
        $form->dataFieldByName('Subquery')->dataValue()
    );
    $search = new Zend_Search_Lucene_Search_Query_Boolean();
    $search->addSubquery($query, true);
    $search->addSubquery($subquery, false);

    // Get hits from the Lucene search engine.
    $hits = ZendSearchLuceneWrapper::find($search);

    // Convert these into a data array containing pagination info etc
    $data = $this->getDataArrayFromHits($hits, $request);

    // Display the results page
    return $this->owner->customise($data)->renderWith(array('Advanced_results', 'Page'));
}