diff --git a/README.md b/README.md index a341097..52d763f 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,123 @@ # Pimcore Elasticsearch Plugin -## What it does +The Elasticsearch plugin for Pimcore Saves/updates contents (text only) of document's (editables) and assets to Elasticsearch. It also provides a query builder to search the index. -* Saves/updates contents (text only) of Document's editables to Elasticsearch - -## Configure +## Features -Copy the distribution config file (`elasticsearchplugin.xml.dist`) in the root of the plugin folder +* Automatic indexing of documents and assets to Elasticsearch when created/updated in Pimcore admin. +* Hooks to add custom properties to the index. +* A simple query builder to retrieve indexed documents. Supports querying, filtering, sorting and pagination. + +## Installation via composer + +The recommended method to install the Pimcore Elasticsearch Plugin is via [Composer](https://getcomposer.org/). + +1 - Add [`byng/pimcore-elasticsearch-plugin`](https://packagist.org/packages/byng/pimcore-elasticsearch-plugin) as a dependency in your project's composer.json file and run `composer install` + +2 - Copy the distribution config file (`elasticsearchplugin.xml.dist`) in the root of the plugin folder to `{PIMCORE_WEBSITE_DIR}/var/config/elasticsearchplugin.xml`. -## Notes +3 - Enable the plugin in Pimcore using the extension manager. + +## Quickstart + +Once the installation has been completed, the first time you create or update a document the Elasticsearch index will be created and the document will be indexed. You can verify that the index exists using curl or [Kibana](https://www.elastic.co/products/kibana). + +## Hooks + +Hooks allow you to hook into the plugin at various points to provide additional functionality. It uses the standard Zend EventManager which Pimcore uses. + +### Registering an event listener example + +For example to register an even listener: + +```php +// @var $eventManager Zend_EventManager_EventManager +$eventManager->attach( + "document.elasticsearch.preIndex", + [__CLASS__, "handlePreIndex"] +); +``` + +The above code will call the `handlePreIndex()` method of the class where it was added whenever a document is ready to be indexed. + +Within the `handlePreIndex()` method you have access to the actual Pimcore document which is being indexed and also the data the plugin has lready extracted. You can add additional properties to the parameters array and they will also be saved to the index: + +```php +public static function handlePreIndex(ZendEvent $event) +{ + /** @var Page $document */ + $document = $event->getTarget(); + $params = $event->getParams(); + + $params["body"]["page"]["customProperty"] = "something"; +} +``` + +## Available hooks + +The following hooks are currently available: + +### document.elasticsearch.preIndex + +This hook is called after the plugin has extracted all the information from the document to index and before it writes the data to Elasticsearch. You can use this hook to write additional/custom properties to the index. + +### asset.elasticsearch.preIndex + +This hook is the asset equivalent of "document.elasticsearch.preIndex". + + +## Querying + +The pluigin provides a simple query builder to make it easy to extract information from Elasticsearch. + +### Example + +```php +use Byng\Pimcore\Elasticsearch\Query\BoolQuery; +use Byng\Pimcore\Elasticsearch\Query\MatchQuery; +use Byng\Pimcore\Elasticsearch\Query\Query; +use Byng\Pimcore\Elasticsearch\Query\QueryBuilder; +use Byng\Pimcore\Elasticsearch\Gateway\PageGateway; + +$boolQuery = new BoolQuery(); +$boolQuery->addMust(new MatchQuery("_all", "something")); + +$query = new Query($boolQuery); + +$queryBuilder = new QueryBuilder(); +$queryBuilder->setQuery($query); +$queryBuilder->setSize(10); // number of results to return + +$pageGateway = PageGateway::getInstance(); +$resultSet = $this->pageGateway->query($queryBuilder); +``` + +The following json request will be geenrated form the above code and sent to Elasticsearch: + +```json +{ + "query": { + "bool": { + "must": [ + { + "match": { + "_all": "something" + } + } + ] + } + }, + "size": 10 +} +``` + +This will retrieve all documents that contain the word "something". + +### Todo -* This plugin requires that the `elasticsearch-mapper-attachments` plugin is installed in -Elasticsearch. If you do not have it installed, plugin installation in Pimcore will fail. -* This plugin automatically creates the indices defined in the configuration file, and also updates -the mapping of some. Please double-check that this will not negatively impact your Elasticsearch -indices. You have been warned - we cannot be held responsible for any loss of data as a result of -the use of this plugin. +* Provide more complete query documentation +* Add support for custom queries, i.e. an array which can be converted to json and posted to Elasticsearch without any processing if the plugin doesn't support the whole Elasticsearch DSL for querying. ## License diff --git a/composer.json b/composer.json index 7695fa9..828aebf 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "byng/pimcore-elasticsearch-plugin", "description": "Elasticsearch Pimcore plugin", - "version": "2.4.0", + "version": "3.0.0", "type": "pimcore-plugin", "license": "MIT", "keywords": [ "pimcore", "elasticsearch", "plugin" ], diff --git a/lib/Byng/Pimcore/Elasticsearch/Gateway/AbstractGateway.php b/lib/Byng/Pimcore/Elasticsearch/Gateway/AbstractGateway.php index ebec556..95e6676 100644 --- a/lib/Byng/Pimcore/Elasticsearch/Gateway/AbstractGateway.php +++ b/lib/Byng/Pimcore/Elasticsearch/Gateway/AbstractGateway.php @@ -14,75 +14,57 @@ namespace Byng\Pimcore\Elasticsearch\Gateway; use Byng\Pimcore\Elasticsearch\Model\ResultsList; -use Byng\Pimcore\Elasticsearch\Query\BoolQuery; -use Byng\Pimcore\Elasticsearch\Query\MatchQuery; -use Byng\Pimcore\Elasticsearch\Query\TermsQuery; use Byng\Pimcore\Elasticsearch\Query\Query; +use Byng\Pimcore\Elasticsearch\Query\QueryBuilder; +use Byng\Pimcore\Elasticsearch\Query\QueryInterface; use Elasticsearch\Client; /** * AbstractGateway * * @author Elliot Wright - * @author Asim Liaquat + * @author Asim Liaquat */ abstract class AbstractGateway { /** * Finds documents by text and term filters * - * @param string $text - * @param array $filters - * @param array $negationFilters - * @param integer|null $offset - * @param integer|null $limit - * @param array $sorting + * @param QueryBuilder $queryBuilder * @param array $additionalOptions * @param array $resultOptions * * @return ResultsList */ public function query( - $text, - array $filters = [], - array $negationFilters = [], - $offset = null, - $limit = null, - array $sorting = [], + QueryBuilder $queryBuilder, array $additionalOptions = [], array $resultOptions = [] ) { - $mustCriteria = []; - $filterCriteria = []; - $mustNotCriteria = []; - - if (!empty($text)) { - $mustCriteria[]["match"]["_all"] = [ - "query" => (string) $text, - "operator" => MatchQuery::OPERATOR_AND - ]; + $body = []; + + if ($query = $queryBuilder->getQuery()) { + $body = $this->processQuery($query); } - - foreach ($filters as $filter) { - $filterCriteria[] = $this->processQuery($filter); + + if ($filter = $queryBuilder->getFilter()) { + $body = array_merge($body, $this->processQuery($filter)); } - - foreach ($negationFilters as $filter) { - /** @var MatchQuery $filter */ - $mustNotCriteria[]["match"][$filter->getField()] = [ - "query" => $filter->getQuery(), - "operator" => $filter->getOperator() - ]; + + if ($from = $queryBuilder->getFrom()) { + $body["from"] = $from; } + if ($size = $queryBuilder->getSize()) { + $body["size"] = $size; + } + + if ($sort = $queryBuilder->getSort()) { + $body["sort"] = $this->processQuery($sort); + } + return $this->findBy( - $mustCriteria, - $filterCriteria, - $mustNotCriteria, - [], - $offset, - $limit, - $sorting, + $body, $additionalOptions, $resultOptions ); @@ -91,26 +73,14 @@ public function query( /** * Executes an Elasticsearch "bool" query * - * @param array $mustCriteria - * @param array $filterCriteria - * @param array $mustNotCriteria - * @param array $shouldCriteria - * @param null $offset - * @param null $limit - * @param array $sorting + * @param array $query * @param array $additionalOptions * @param array $resultOptions * * @return mixed */ abstract public function findBy( - array $mustCriteria = [], - array $filterCriteria = [], - array $mustNotCriteria = [], - array $shouldCriteria = [], - $offset = null, - $limit = null, - array $sorting = [], + array $query, array $additionalOptions = [], array $resultOptions = [] ); @@ -121,13 +91,7 @@ abstract public function findBy( * @param Client $client * @param string $index * @param string $type - * @param array $mustCriteria - * @param array $filterCriteria - * @param array $mustNotCriteria - * @param array $shouldCriteria - * @param null|integer $offset - * @param null|integer $limit - * @param array $sorting + * @param array $query * @param array $additionalOptions * * @return array @@ -136,40 +100,11 @@ protected function doSearch( Client $client, $index, $type, - array $mustCriteria = [], - array $filterCriteria = [], - array $mustNotCriteria = [], - array $shouldCriteria = [], - $offset = null, - $limit = null, - $sorting = [], + $query, $additionalOptions = [] ) { - $query = [ - "query" => [ - "bool" => [ - "must" => $mustCriteria, - "filter" => $filterCriteria, - "must_not" => $mustNotCriteria, - "should" => $shouldCriteria - ] - ], - ]; - $body = $additionalOptions + $query; - - if ($offset) { - $body["from"] = $offset; - } - - if ($limit) { - $body["size"] = $limit; - } - - if (!empty($sorting)) { - $body["sort"] = $sorting; - } - + return $client->search([ "index" => $index, "type" => $type, @@ -184,21 +119,25 @@ protected function doSearch( * * @return array */ - protected function processQuery(Query $query) + protected function processQuery(QueryInterface $query) { switch ($query->getType()) { + + case "query": + $result["query"] = $this->processQuery($query->getBoolQuery()); + break; + + case "filter": + $result["filter"] = $this->processQuery($query->getBoolQuery()); + break; + case "bool": - /** @var BoolQuery $query */ $boolResult = []; foreach ($query->getMust() as $must) { $boolResult["must"][] = $this->processQuery($must); } - foreach ($query->getFilter() as $filter) { - $boolResult["filter"][] = $this->processQuery($filter); - } - foreach ($query->getShould() as $should) { $boolResult["should"][] = $this->processQuery($should); } @@ -211,23 +150,32 @@ protected function processQuery(Query $query) $result["bool"] = $boolResult; break; + case "match": - /** @var MatchQuery $query */ $result = []; - $result["match"][$query->getField()] = [ - "query" => $query->getQuery(), - "operator" => $query->getOperator() - ]; - break; - case "terms": - /** @var TermsQuery $query */ - $result = []; - $result["terms"][$query->getField()] = $query->getTerms(); + + if ($operator = $query->getOperator()) { + $result["match"][$query->getField()] = [ + "query" => $query->getQuery(), + "operator" => $operator + ]; + } else { + $result["match"][$query->getField()] = $query->getQuery(); + } break; + case "range": $result = []; $result["range"][$query->getField()] = $query->getRanges(); break; + + case "sort": + $result = []; + foreach ($query->getCriteria() as $column => $order) { + $result[$column]["order"] = $order; + } + break; + default: throw new \InvalidArgumentException(sprintf( "Unknown query type '%s' given.", diff --git a/lib/Byng/Pimcore/Elasticsearch/Gateway/AssetGateway.php b/lib/Byng/Pimcore/Elasticsearch/Gateway/AssetGateway.php index dbbb458..ce5cfcb 100644 --- a/lib/Byng/Pimcore/Elasticsearch/Gateway/AssetGateway.php +++ b/lib/Byng/Pimcore/Elasticsearch/Gateway/AssetGateway.php @@ -180,13 +180,7 @@ public function exists(Asset $asset) * {@inheritdoc} */ public function findBy( - array $mustCriteria = [], - array $filterCriteria = [], - array $mustNotCriteria = [], - array $shouldCriteria = [], - $offset = null, - $limit = null, - array $sorting = [], + array $query, array $additionalOptions = [], array $resultOptions = [] ) { @@ -200,13 +194,7 @@ public function findBy( $this->client, $this->index, $this->type, - $mustCriteria, - $filterCriteria, - $mustNotCriteria, - $shouldCriteria, - $offset, - $limit, - $sorting, + $query, $additionalOptions ); diff --git a/lib/Byng/Pimcore/Elasticsearch/Gateway/PageGateway.php b/lib/Byng/Pimcore/Elasticsearch/Gateway/PageGateway.php index b6c661f..2fbd815 100644 --- a/lib/Byng/Pimcore/Elasticsearch/Gateway/PageGateway.php +++ b/lib/Byng/Pimcore/Elasticsearch/Gateway/PageGateway.php @@ -198,13 +198,7 @@ public function exists(Page $document) * {@inheritdoc} */ public function findBy( - array $mustCriteria = [], - array $filterCriteria = [], - array $mustNotCriteria = [], - array $shouldCriteria = [], - $offset = null, - $limit = null, - array $sorting = [], + array $query, array $additionalOptions = [], array $resultOptions = [] ) { @@ -212,13 +206,7 @@ public function findBy( $this->client, $this->index, $this->type, - $mustCriteria, - $filterCriteria, - $mustNotCriteria, - $shouldCriteria, - $offset, - $limit, - $sorting, + $query, $additionalOptions ); diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/BoolQuery.php b/lib/Byng/Pimcore/Elasticsearch/Query/BoolQuery.php index 36b49fb..ccc1a87 100644 --- a/lib/Byng/Pimcore/Elasticsearch/Query/BoolQuery.php +++ b/lib/Byng/Pimcore/Elasticsearch/Query/BoolQuery.php @@ -19,46 +19,38 @@ * Encapsulates a "bool" query's data. * * @author Elliot Wright + * @author Asim Liaquat */ -final class BoolQuery implements Query +final class BoolQuery implements QueryInterface { /** * @var array */ - private $must; + private $must = []; /** * @var array */ - private $filter; + private $should = []; /** * @var array */ - private $should; - - /** - * @var array - */ - private $mustNot; - + private $mustNot = []; /** * BoolQuery constructor. * * @param array $must - * @param array $filter * @param array $should * @param array $mustNot */ public function __construct( array $must = [], - array $filter = [], array $should = [], array $mustNot = [] ) { $this->must = $must; - $this->filter = $filter; $this->should = $should; $this->mustNot = $mustNot; } @@ -73,16 +65,6 @@ public function getMust() return $this->must; } - /** - * Get filter - * - * @return array - */ - public function getFilter() - { - return $this->filter; - } - /** * Get should * @@ -104,73 +86,68 @@ public function getMustNot() } /** - * Add a must clause - * - * @param Query $must - * + * Add a "must" clause + * + * @param QueryInterface $must + * * @return BoolQuery */ - public function withMust(Query $must) + public function addMust(QueryInterface $must) { - return new BoolQuery( - array_merge($this->must, $must), - $this->filter, - $this->should, - $this->mustNot - ); + $this->must[] = $must; + return $this; } /** - * Add a filter clause - * - * @param Query $filter - * + * Add a "should" clause + * + * @param QueryInterface $should + * * @return BoolQuery */ - public function withFilter(Query $filter) + public function addShould(QueryInterface $should) { - return new BoolQuery( - $this->must, - array_merge($this->filter, [ $filter ]), - $this->should, - $this->mustNot - ); + $this->should[] = $should; + return $this; } /** - * Add a should clause - * - * @param Query $should - * + * Add a "must_not" + * + * @param QueryInterface $mustNot + * * @return BoolQuery */ - public function withShould(Query $should) + public function addMustNot(QueryInterface $mustNot) { - return new BoolQuery( - $this->must, - $this->filter, - array_merge($this->should, [ $should ]), - $this->mustNot - ); + $this->mustNot[] = $mustNot; + return $this; } /** - * Add a must_not clause - * - * @param Query $mustNot - * - * @return BoolQuery + * Resets all data which has been added + * + * @return void */ - public function withMustNot(Query $mustNot) + public function clear() { - return new BoolQuery( - $this->must, - $this->filter, - $this->should, - array_merge($this->mustNot, [ $mustNot ]) - ); + $this->must = []; + $this->mustNot = []; + $this->should = []; } - + + /** + * Checkls whether any "must", "must_not" or "should" claues have been added. + * + * @return bool + */ + public function isEmpty() + { + return count($this->must) === 0 + && count($this->mustNot) === 0 + && count($this->should) === 0; + } + /** * {@inheritdoc} */ diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/Filter.php b/lib/Byng/Pimcore/Elasticsearch/Query/Filter.php new file mode 100644 index 0000000..38ee714 --- /dev/null +++ b/lib/Byng/Pimcore/Elasticsearch/Query/Filter.php @@ -0,0 +1,67 @@ + + */ +class Filter implements QueryInterface +{ + /** + * @var BoolQuery + */ + private $boolQuery; + + /** + * Filter constructor. + * + * @param BoolQuery $boolQuery + */ + public function __construct(BoolQuery $boolQuery = null) + { + $this->boolQuery = $boolQuery; + } + + /** + * Get bool query + * + * @return BoolQuery + */ + public function getBoolQuery() + { + return $this->boolQuery; + } + + /** + * Set bool query + * + * @param BoolQuery $boolQuery + */ + public function setBoolQuery(BoolQuery $boolQuery) + { + $this->boolQuery = $boolQuery; + } + + /** + * {@inheritdoc} + */ + public function getType() + { + return "filter"; + } +} diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/MatchQuery.php b/lib/Byng/Pimcore/Elasticsearch/Query/MatchQuery.php index 6341502..b61ecf8 100644 --- a/lib/Byng/Pimcore/Elasticsearch/Query/MatchQuery.php +++ b/lib/Byng/Pimcore/Elasticsearch/Query/MatchQuery.php @@ -19,8 +19,9 @@ * Encapsulates a "match" query's data. * * @author Elliot Wright + * @author Asim Liaquat */ -final class MatchQuery implements Query +final class MatchQuery implements QueryInterface { const OPERATOR_AND = "and"; const OPERATOR_OR = "or"; @@ -48,21 +49,23 @@ final class MatchQuery implements Query * @param string|array $query * @param string $operator */ - public function __construct($field, $query, $operator = self::OPERATOR_AND) + public function __construct($field, $query, $operator = null) { $this->field = $field; $this->query = $query; $this->operator = $operator; - switch ($this->operator) { - case self::OPERATOR_AND: - case self::OPERATOR_OR: - break; - default: - throw new \InvalidArgumentException(sprintf( - "Unexpected operator found: '%s'", - $this->operator - )); + if ($operator !== null) { + switch ($this->operator) { + case self::OPERATOR_AND: + case self::OPERATOR_OR: + break; + default: + throw new \InvalidArgumentException(sprintf( + "Unexpected operator found: '%s'", + $this->operator + )); + } } } diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/Query.php b/lib/Byng/Pimcore/Elasticsearch/Query/Query.php index 98fe357..e2516cc 100644 --- a/lib/Byng/Pimcore/Elasticsearch/Query/Query.php +++ b/lib/Byng/Pimcore/Elasticsearch/Query/Query.php @@ -16,14 +16,52 @@ /** * Query * - * @author Elliot Wright + * Encapsulates a query's data. + * + * @author Asim Liaquat */ -interface Query +class Query implements QueryInterface { /** - * Get the type of query that this is + * @var BoolQuery + */ + private $boolQuery; + + /** + * Query constructor. * - * @return string + * @param BoolQuery $boolQuery + */ + public function __construct(BoolQuery $boolQuery = null) + { + $this->boolQuery = $boolQuery; + } + + /** + * Get bool query + * + * @return BoolQuery + */ + public function getBoolQuery() + { + return $this->boolQuery; + } + + /** + * Set bool query + * + * @param BoolQuery $boolQuery + */ + public function setBoolQuery(BoolQuery $boolQuery) + { + $this->boolQuery = $boolQuery; + } + + /** + * {@inheritdoc} */ - public function getType(); + public function getType() + { + return "query"; + } } diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/QueryBuilder.php b/lib/Byng/Pimcore/Elasticsearch/Query/QueryBuilder.php new file mode 100644 index 0000000..baf5b54 --- /dev/null +++ b/lib/Byng/Pimcore/Elasticsearch/Query/QueryBuilder.php @@ -0,0 +1,160 @@ + + */ +class QueryBuilder +{ + /** + * @var Query + */ + private $query; + + /** + * @var Filter + */ + private $filter; + + /** + * @var int + */ + private $size = 10; + + /** + * @var int + */ + private $from; + + /** + * @var Sort + */ + private $sort; + + /** + * QueryBuilder constructor + * + * @param Query $query + * @param Filter $filter + */ + public function __construct(Query $query = null, Filter $filter = null) + { + $this->query = $query; + $this->filter = $filter; + } + + /** + * Get query + * + * @return Query + */ + public function getQuery() + { + return $this->query; + } + + /** + * Get filter + * + * @return Filter + */ + public function getFilter() + { + return $this->filter; + } + + /** + * Set query + * + * @param Query $query + */ + public function setQuery(Query $query) + { + $this->query = $query; + } + + /** + * Set filter + * + * @param Filter $filter + */ + public function setFilter(Filter $filter) + { + $this->filter = $filter; + } + + /** + * Get the number or results to return + * + * @return int + */ + public function getSize() + { + return $this->size; + } + + /** + * Set the number of results to return + * + * @param int $size + */ + public function setSize($size) + { + $this->size = $size; + } + + /** + * Get the offset to fetch the results from + * + * @return int|null + */ + public function getFrom() + { + return $this->from; + } + + /** + * Set the offset to fetch the results from + * + * @param int $from + */ + public function setFrom($from) + { + $this->from = $from; + } + + /** + * Get sort criteria + * + * @return Sort + */ + public function getSort() + { + return $this->sort; + } + + /** + * Set sort criteria + * + * @param Sort $sort + */ + public function setSort(Sort $sort) + { + $this->sort = $sort; + } + +} diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/QueryInterface.php b/lib/Byng/Pimcore/Elasticsearch/Query/QueryInterface.php new file mode 100644 index 0000000..2aeebbc --- /dev/null +++ b/lib/Byng/Pimcore/Elasticsearch/Query/QueryInterface.php @@ -0,0 +1,30 @@ + + * @author Asim Liaquat + */ +interface QueryInterface +{ + /** + * Get the type of query that this is + * + * @return string + */ + public function getType(); +} diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/RangeQuery.php b/lib/Byng/Pimcore/Elasticsearch/Query/RangeQuery.php index 5a1e02c..f6b4eb3 100644 --- a/lib/Byng/Pimcore/Elasticsearch/Query/RangeQuery.php +++ b/lib/Byng/Pimcore/Elasticsearch/Query/RangeQuery.php @@ -19,9 +19,9 @@ * Allows searching for data which falls within a certain range. Useful for * dates etc. * - * @author Asim Liaquat + * @author Asim Liaquat */ -final class RangeQuery implements Query +final class RangeQuery implements QueryInterface { const OPERATOR_GT = "gt"; const OPERATOR_GTE = "gte"; diff --git a/lib/Byng/Pimcore/Elasticsearch/Query/Sort.php b/lib/Byng/Pimcore/Elasticsearch/Query/Sort.php new file mode 100644 index 0000000..13e26a0 --- /dev/null +++ b/lib/Byng/Pimcore/Elasticsearch/Query/Sort.php @@ -0,0 +1,74 @@ + + */ +class Sort implements QueryInterface +{ + /** + * @var array + */ + private $data = []; + + /** + * Sort constructor. + */ + public function __construct() + { + } + + /** + * Add a sorting criteria. Can be called multiple times to sort by more than + * one column. + * + * @param string $column + * @param string $order + */ + public function addCriteria($column, $order) + { + $this->data[$column] = $order; + } + + /** + * Get sort criteria + * + * @return array + */ + public function getCriteria() + { + return $this->data; + } + + /** + * Resets the previously added criteria + */ + public function clear() + { + $this->data = []; + } + + /** + * {@inheritdoc} + */ + public function getType() + { + return "sort"; + } +}