README

注意： 此包已迁移至 FOSElasticaBundle，在 FriendsOfSymfony 组织下。

Elastica 集成到 Symfony2

安装

安装 elasticsearch

http://www.elasticsearch.org/guide/reference/setup/installation.html

安装 Elastica

下载

使用子模块

git submodule add git://github.com/ruflin/Elastica vendor/elastica

使用克隆

git clone git://github.com/ruflin/Elastica vendor/elastica

使用 vendors 脚本

将以下行添加到您的 deps 文件中

[Elastica]
    git=git://github.com/ruflin/Elastica.git
    target=elastica

注册自动加载

// app/autoload.php

$loader->registerPrefixes(array(
    ...
    'Elastica' => __DIR__.'/../vendor/elastica/lib',
));

安装 ElasticaBundle

仅使用 Symfony2 master 分支的 master 分支，使用 2.0 分支与 Symfony2.0.x 版本。

下载

使用子模块

git submodule add git://github.com/Exercise/FOQElasticaBundle vendor/bundles/FOQ/ElasticaBundle

使用克隆

git clone git://github.com/Exercise/FOQElasticaBundle vendor/bundles/FOQ/ElasticaBundle

使用 vendors 脚本

将以下行添加到您的 deps 文件中

[FOQElasticaBundle]
    git=git://github.com/Exercise/FOQElasticaBundle.git
    target=bundles/FOQ/ElasticaBundle

对于与 Symfony2.0.x 版本一起使用的 2.0 分支，请添加以下内容

[FOQElasticaBundle]
    git=git://github.com/Exercise/FOQElasticaBundle.git
    target=bundles/FOQ/ElasticaBundle
    version=origin/2.0

运行 vendors 脚本

$ php bin/vendors install

注册自动加载

// app/autoload.php

$loader->registerNamespaces(array(
    ...
    'FOQ' => __DIR__.'/../vendor/bundles',
));

注册包

// app/AppKernel.php

public function registerBundles()
{
    return array(
        // ...
        new FOQ\ElasticaBundle\FOQElasticaBundle(),
        // ...
    );
}

基本配置

声明一个客户端

Elasticsearch 客户端类似于数据库连接。大多数情况下，您只需要一个。

#app/config/config.yml
foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }

声明一个索引

Elasticsearch 索引类似于 Doctrine 实体管理器。大多数情况下，您只需要一个。

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default

在这里，我们创建了一个“网站”索引，使用我们的“默认”客户端。

我们的索引现在作为一个服务可用：foq_elastica.index.website。它是一个 Elastica_Index 实例。

如果您需要不同的索引名称与服务名称，例如，为了在不同的环境中拥有不同的索引，则可以使用 index_name 键来更改索引名称。服务名称将在所有环境中保持相同。

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            index_name: website_qa

服务 ID 将为 foq_elastica.index.website，但底层的索引名称是 website_qa。

声明一个类型

Elasticsearch 类型类似于 Doctrine 实体仓库。

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            types:
                user:
                    mappings:
                        username: { boost: 5 }
                        firstName: { boost: 3 }
                        lastName: { boost: 3 }
                        aboutMe: ~

我们的类型现在作为一个服务可用：foq_elastica.index.website.user。它是一个 Elastica_Type 实例。

声明父字段

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            types:
                comment:
                    mappings:
                        post: {_parent: { type: "post", identifier: "id" } }
                        date: { boost: 5 }
                        content: ~

声明嵌套或对象

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            types:
                post:
                    mappings:
                        date: { boost: 5 }
                        title: { boost: 3 }
                        content: ~
                        comments:
                            type: "nested"
                            properties:
                                date: { boost: 5 }
                                content: ~

填充类型

php app/console foq:elastica:populate

此命令会删除并创建已声明的索引和类型。它将配置的映射应用于类型。

此命令需要提供者将新文档插入到Elasticsearch类型中。有两种创建提供者的方式。如果你的Elasticsearch类型与Doctrine仓库或Propel查询相匹配，请选择持久性自动提供者。或者，为了获得完全的灵活性，请选择手动提供者。

持久性自动提供者

如果我们想从Doctrine仓库或Propel查询中索引实体，一些配置将让ElasticaBundle为我们完成此操作。

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            types:
                user:
                    mappings:
                        username: { boost: 5 }
                        firstName: { boost: 3 }
                        # more mappings...
                    persistence:
                        driver: orm # orm, mongodb, propel are available
                        model: Application\UserBundle\Entity\User
                        provider: ~

实际上支持三种驱动程序：orm、mongodb和propel。

使用自定义Doctrine查询构建器

您可以通过指定自定义查询构建器方法来控制哪些实体将被索引。

                    persistence:
                        driver: orm
                        model: Application\UserBundle\Entity\User
                        provider:
                            query_builder_method: createIsActiveQueryBuilder

您的仓库必须实现此方法并返回一个Doctrine查询构建器。

Propel尚不支持此功能。

更改批量大小

默认情况下，ElasticaBundle将以100个文档的包来索引文档。您可以在提供者配置中更改此值。

                    persistence:
                        driver: orm
                        model: Application\UserBundle\Entity\User
                        provider:
                            batch_size: 100

更改文档标识字段

默认情况下，ElasticaBundle将使用您的实体的id字段作为Elasticsearch文档标识。您可以在持久性配置中更改此值。

                    persistence:
                        driver: orm
                        model: Application\UserBundle\Entity\User
                        identifier: id

手动提供者

创建一个具有“foq_elastica.provider”标签和为服务提供的索引和类型的属性的服务。

    <service id="acme.search_provider.user" class="Acme\UserBundle\Search\UserProvider">
        <tag name="foq_elastica.provider" index="website" type="user" />
        <argument type="service" id="foq_elastica.index.website.user" />
    </service>

其类必须实现FOQ\ElasticaBundle\Provider\ProviderInterface。

    <?php

    namespace Acme\UserBundle\Provider;

    use FOQ\ElasticaBundle\Provider\ProviderInterface;
    use Elastica_Type;

    class UserProvider implements ProviderInterface
    {
        protected $userType;

        public function __construct(Elastica_Type $userType)
        {
            $this->userType = $userType;
        }

        /**
         * Insert the repository objects in the type index
         *
         * @param Closure $loggerClosure
         */
        public function populate(Closure $loggerClosure = null)
        {
            if ($loggerClosure) {
                $loggerClosure('Indexing users');
            }

            $document = new \Elastica_Document();
            $document->setData(array('username' => 'Bob'));
            $this->userType->addDocuments(array($document));
        }
    }

您可以在src/FOQ/ElasticaBundle/Doctrine/AbstractProvider.php中找到一个更完整的实现示例。

搜索

您可以使用作为服务提供的索引和Elastica类型对象来执行搜索。

/** var Elastica_Type */
$userType = $this->container->get('foq_elastica.index.website.user');

/** var Elastica_ResultSet */
$resultSet = $userType->search('bob');

Doctrine/Propel查找器

如果您的Elasticsearch类型绑定到Doctrine实体仓库或Propel查询，则当您进行搜索时，您可以获取实体而不是Elastica结果。在您的配置中声明您想要一个Doctrine/Propel查找器。

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            types:
                user:
                    mappings:
                        # your mappings
                    persistence:
                        driver: orm
                        model: Application\UserBundle\Entity\User
                        provider: ~
                        finder: ~

您现在可以使用foq_elastica.finder.website.user服务

/** var FOQ\ElasticaBundle\Finder\TransformedFinder */
$finder = $container->get('foq_elastica.finder.website.user');

/** var array of Acme\UserBundle\Entity\User */
$users = $finder->find('bob');

/** var array of Acme\UserBundle\Entity\User limited to 10 results */
$users = $finder->find('bob', 10);

您甚至可以获得分页结果！

Pagerfanta

/** var Pagerfanta\Pagerfanta */
$userPaginator = $finder->findPaginated('bob');

Knp分页器

$paginator = $this->get('knp_paginator');
$userPaginator = $paginator->paginate($finder->createPaginatorAdapter('bob'));

您还可以从查找器中获得Elastica结果和实体。然后您可以从Elastica_Result访问得分、高亮等，同时仍然可以获得实体。

/** var array of FOQ\ElasticaBundle\HybridResult */
$hybridResults = $finder->findHybrid('bob');
foreach ($hybridResults as $hybridResult) {

    /** var  Acme\UserBundle\Entity\User */
    $user = $hybridResult->getTransformed();

    /** var  Elastica_Result */
    $result = $hybridResult->getResult();
}

索引宽查找器

您还可以定义一个将在整个索引上工作的查找器。根据以下内容调整您的索引配置

foq_elastica:
    indexes:
        website:
            client: default
            finder: ~

您现在可以使用索引宽查找器服务foq_elastica.finder.website

/** var FOQ\ElasticaBundle\Finder\MappedFinder */
$finder = $container->get('foq_elastica.finder.website');

// Returns a mixed array of any objects mapped
$results = $finder->find('bob');

仓库

除了使用特定 Doctrine/Propel 实体的查找服务外，您还可以为每个驱动程序使用管理服务，为实体获取一个搜索用的存储库。这允许您使用相同的而不是特定的查找服务。例如

/** var FOQ\ElasticaBundle\Manager\RepositoryManager */
$repositoryManager = $container->get('foq_elastica.manager.orm');

/** var FOQ\ElasticaBundle\Repository */
$repository = $repositoryManager->getRepository('UserBundle:User');

/** var array of Acme\UserBundle\Entity\User */
$users = $repository->find('bob');

您也可以指定实体的全名而不是快捷语法

/** var FOQ\ElasticaBundle\Repository */
$repository = $repositoryManager->getRepository('Application\UserBundle\Entity\User');

2.0 分支不支持使用 UserBundle:User 风格的语法，您必须使用实体的全名。

默认管理器

如果您只使用一个驱动程序，则其管理服务将自动别名为 foq_elastica.manager。因此，上面的示例可以简化为

/** var FOQ\ElasticaBundle\Manager\RepositoryManager */
$repositoryManager = $container->get('foq_elastica.manager');

/** var FOQ\ElasticaBundle\Repository */
$repository = $repositoryManager->getRepository('UserBundle:User');

/** var array of Acme\UserBundle\Entity\User */
$users = $repository->find('bob');

如果您使用多个驱动程序，则可以使用 default_manager 参数选择哪个被别名为 foq_elastica.manager

foq_elastica:
    default_manager: mongodb #defauults to orm
    clients:
        default: { host: localhost, port: 9200 }
    #--

自定义存储库

除了默认存储库外，您还可以为实体创建自定义存储库并添加特定搜索的方法。这些需要扩展 FOQ\ElasticaBundle\Repository 以访问查找器

<?php

namespace Acme\ElasticaBundle\SearchRepository;

use FOQ\ElasticaBundle\Repository;

class UserRepository extends Repository
{
    public function findWithCustomQuery($searchText)
    {
        // build $query with Elastica objects
        $this->find($query);
    }
}

要使用自定义存储库，请在实体的映射中指定它

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            types:
                user:
                    mappings:
                        # your mappings
                    persistence:
                        driver: orm
                        model: Application\UserBundle\Entity\User
                        provider: ~
                        finder: ~
                        repository: Acme\ElasticaBundle\SearchRepository\UserRepository

然后，当使用从管理器返回的存储库时，将可用自定义查询

/** var FOQ\ElasticaBundle\Manager\RepositoryManager */
$repositoryManager = $container->get('foq_elastica.manager');

/** var FOQ\ElasticaBundle\Repository */
$repository = $repositoryManager->getRepository('UserBundle:User');

/** var array of Acme\UserBundle\Entity\User */
$users = $repository->findWithCustomQuery('bob');

或者，您可以使用实体的注解来指定自定义存储库

<?php

namespace Application\UserBundle\Entity;

use FOQ\ElasticaBundle\Configuration\Search;

/**
 * @Search(repositoryClass="Acme\ElasticaBundle\SearchRepository\UserRepository")
 */
class User
{

   //---

}

实时、选择性索引更新

如果您使用 Doctrine 集成，可以在对象被添加、更新或删除时让 ElasticaBundle 自动更新索引。它使用 Doctrine 生命周期事件。声明您希望在实时更新索引

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        website:
            client: default
            types:
                user:
                    mappings:
                        # your mappings
                    persistence:
                        driver: orm
                        model: Application\UserBundle\Entity\User
                        listener: # by default, listens to "insert", "update" and "delete"

现在，每当关联的 Doctrine 存储库的状态改变时，索引将自动更新。当创建新的 User 时，无需重新填充整个 "user" 索引。

您也可以选择仅监听某些事件

                    persistence:
                        listener:
                            insert: true
                            update: false
                            delete: true

Propel尚不支持此功能。

检查实体方法以进行监听

如果您使用监听器来更新索引，您可能需要在索引之前验证实体（例如，仅索引 "public" 实体）。通常，您希望监听器与提供者的查询条件一致。这可以通过使用 is_indexable_callback 配置参数来实现

                    persistence:
                        listener:
                            is_indexable_callback: "isPublic"

如果 is_indexable_callback 是一个字符串，并且实体具有具有指定名称的方法，则监听器将只为返回 true 的实体进行索引。您还可以提供服务和方法名称对

                    persistence:
                        listener:
                            is_indexable_callback: [ "%custom_service_id%", "isIndexable" ]

在这种情况下，回调将是指定服务上的 isIndexable() 方法，并且要考虑索引的对象将作为唯一参数传递。这允许您进行更复杂的验证（例如，ACL 检查）。

正如您所期望的，只有当回调返回 true 时，新实体才会被索引。此外，根据回调返回 true 或 false，修改的实体将更新或从索引中删除。删除监听器忽略回调。

Propel尚不支持此功能。

高级 Elasticsearch 配置

在声明类型时可以指定任何设置。例如，要启用自定义分析器，您可以编写

foq_elastica:
    indexes:
        doc:
            settings:
                index:
                    analysis:
                        analyzer:
                            my_analyzer:
                                type: custom
                                tokenizer: lowercase
                                filter   : [my_ngram]
                        filter:
                            my_ngram:
                                type: "nGram"
                                min_gram: 3
                                max_gram: 5
            types:
                blog:
                    mappings:
                        title: { boost: 8, analyzer: my_analyzer }

覆盖客户端类以抑制异常

默认情况下，Elastica客户端库的异常将通过包的Client类传播。例如，如果Elasticsearch服务器离线，发送请求将导致抛出Elastica_Exception_Client异常。根据您的需求，可能希望抑制这些异常，并允许搜索静默失败。

实现这一点的 一种方法是用自定义类覆盖foq_elastica.client.class服务容器参数。在以下示例中，我们覆盖了Client::request()方法，并在发生异常时返回等效的空搜索响应。

<?php

namespace Acme\ElasticaBundle;

use FOQ\ElasticaBundle\Client as BaseClient;

class Client extends BaseClient
{
    public function request($path, $method, $data = array())
    {
        try {
            return parent::request($path, $method, $data);
        } catch (\Elastica_Exception_Abstract $e) {
            return new \Elastica_Response('{"took":0,"timed_out":false,"hits":{"total":0,"max_score":0,"hits":[]}}');
        }
    }
}

高级查询示例

如果您想执行更复杂的查询，这里有一个使用snowball词干提取算法的示例。

它使用title、tags和categoryIds搜索Article实体。结果必须至少匹配一个指定的categoryIds，并且应该匹配title或tags标准。此外，我们定义了一个snowball分析器，用于对title字段的查询应用。

$finder = $this->container->get('foq_elastica.finder.website.article');
$boolQuery = new \Elastica_Query_Bool();

$fieldQuery = new \Elastica_Query_Text();
$fieldQuery->setFieldQuery('title', 'I am a title string');
$fieldQuery->setFieldParam('title', 'analyzer', 'my_analyzer');
$boolQuery->addShould($fieldQuery);

$tagsQuery = new \Elastica_Query_Terms();
$tagsQuery->setTerms('tags', array('tag1', 'tag2'));
$boolQuery->addShould($tagsQuery);

$categoryQuery = new \Elastica_Query_Terms();
$categoryQuery->setTerms('categoryIds', array('1', '2', '3'));
$boolQuery->addMust($categoryQuery);

$data = $finder->find($boolQuery);

配置

foq_elastica:
    clients:
        default: { host: localhost, port: 9200 }
    indexes:
        site:
            settings:
                index:
                  analysis:
                        analyzer:
                            my_analyzer:
                                type: snowball
                                language: English
            types:
                article:
                    mappings:
                        title: { boost: 10, analyzer: my_analyzer }
                        tags:
                        categoryIds:
                    persistence:
                        driver: orm
                        model: Acme\DemoBundle\Entity\Article
                        provider:
                        finder: