haguiry/awscloudsearchbundle

AWS Cloud Search bundle for Symfony 2

AWSCloudSearchBundle

Note: This bundle is in alpha development stage and is as such not for production environments. Our aim is to complete development and testing in the next two weeks. All contributions welcome., _(*1)

This bundle is designed to make it easier to integrate Amazon Cloud Search with Symfony2 projects to index entities regardless of database implementation., _(*2)

Full AWS Cloud Search API Doco available at: http://docs.aws.amazon.com/cloudsearch/latest/developerguide/SvcIntro.html, _(*3)

1) Installation

Install PHP Curl module:, _(*4)

    yum install php-curl

Add to composer.json:, _(*5)

    "redeyeapps/awscloudsearchbundle" : "dev-master"

2) Configuration

In your Symfony2 projects config.yml you needs to configure you AWS indexes. doc_endpoint and search_endpoint can be copied directly for AWS Cloud Search console, remember to change protocol to https for ssl encryption., _(*6)

Example Configuration:, _(*7)

aws_cloud_search: 
indexes: 
    index1 :
        doc_endpoint: https://doc-index1.us-west-1.cloudsearch.amazonaws.com
        search_endpoint: https://search-index1.cloudsearch.amazonaws.com
        lang: en
    index2 :
        doc_endpoint: https://doc-index2.us-west-1.cloudsearch.amazonaws.com
        search_endpoint: https://search-index2-test.cloudsearch.amazonaws.com
        lang: en

Also remember to setup your AWS Cloud Search access rules to allow indexing and searching from appropriate ip's., _(*8)

3) Indexer Usage

To index documents you need to create a JSON array of documents that match the AWS Cloud Search fields format you configured in the AWS console and post it to Cloud Search., _(*9)

To index changes to entities (adds/updates/removes) it is recommended you us an event subscriber to doctrine persist events to index entity changes on the fly., _(*10)

To create a subscriber see: http://symfony.com/doc/current/cookbook/doctrine/event_listeners_subscribers.html, _(*11)

For full example subscriber see Resources/doc/ExampleSubscriber.php, _(*12)

To do initial indexing of entities it is recommended you use a Symfony2 command. For full example indexing command see Resources/doc/ExampleIndexCommand.php, _(*13)

Notes on Converting Entity to Json

There are a couple of approaches, one is to use this bundle: http://jmsyst.com/bundles/JMSSerializerBundle/master/installation, _(*14)

This bundle is pretty complex to setup and adds a few extra depenacies. In our case we have created a simple function on the entities we need to index called getSearchFields() which manually converts the entity to an object that that matches the fields configured for our indexes. This is then json encoded and passed to the indexer service., _(*15)

Example:, _(*16)

    //src/MyOrg/MyBundle/Entity/MyEntity.php
    public function getSearchFields() {
        $obj = new \StdClass;
        $obj->id = $this->getId();
        $number = $this->getNumber();

        //Be careful with null fields
        if($code == null) {
            $number = '';
        }
        $obj->number = $number;

        $title = $this->getTitle();
        if($title == null) {
            $title = '';
        }
        $obj->title = $title;

        //Groups Array
        $groups = array();
        foreach($this->getGroups() as $group) {
            $groups[] = $group->getId();
        }

        if(count($groups) > 0){
            $obj->groups = $groups;
        }

        return $obj;
    }

This matches an index with the fields:, _(*17)

    id : uint
    number : uint
    title : text
    groups : uint

4) Search Usage

Searching using the CloudSearchClient service is pretty straight forward (the only required setting is setIndex):, _(*18)

    // Create search client
    $cloudsearcher = $this->get('cloudsearchclient');

    //Specify index to search. Must match indexname in config.yml
    $cloudsearcher->setIndex('redeyevms');

    //Set text fields to search with search term
    $cloudsearcher->addSearchField('title');
    $cloudsearcher->addSearchField('desc');

    //Set fields to recieve in results
    $cloudsearcher->addReturnField('title');

    //Set a sort field
    $cloudsearcher->addSort('title', 'ASC');

    //Set offsets and result limit, useful for paging.
    $cloudsearcher->setOffset($offset);
    $cloudsearcher->setLimit($resultlength);

    // Match mode, one of: normal, exact, startswith, endswith, any. Defaults to normal.
    $cloudsearcher->setMatchMode('startswith');

    //Add a filter to search
    $cloudsearcher->addFilter('genre', 'or', array('horror', 'sci-fi')); //Genre can be either horror or sci-fi.

    //Do search with string as search term
    $results = $cloudsearcher->search('star wars');      

Format of results is documented here: http://docs.aws.amazon.com/cloudsearch/latest/developerguide/Search.Response.html, _(*19)