firesphere / elastic-search
Search a SilverStripe site with Elastic Enterprise or Elastic search
Requires
- php: >=8.0
- ext-json: *
- elasticsearch/elasticsearch: ^8.10
- firesphere/searchbackend: ^1.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.35
- phpunit/phpunit: ^9.5
- silverstripe/recipe-cms: ^4|^5
Suggests
- ext-pcntl: Support for multi-core indexing
Conflicts
This package is auto-updated.
Last update: 2024-11-09 04:16:00 UTC
README
Elasticsearch implementation for Silverstripe.
Disclaimer
If this module breaks your website, you get to keep all the pieces.
Acknowledgements
- Pikselin Ltd., Part of this module has been created thanks to support from Pikselin
- Marco
Sheepy
Hermo, the amount of pre-work from the Solr module, done by Marco, has made this work a lot easier
Installation
composer require firesphere/elastic
Requirements
- PHP8+
- Elasticsearch 8.10+
- Silverstripe Framework 4 || 5
Elastic search with Silverstripe
This module provides an API similar to the Solr Search module.
Basic search index
- Create an API-index in your ElasticSearch instance
- If you have Elastic Enterprise, this is under Search => API
- Create an API key
- You can use a username/password, but API key is recommended
Configuring the service
Configuration is done in YML:
---
Name: MyElastic
---
Firesphere\ElasticSearch\Services\ElasticCoreService:
config:
endpoint:
- host: "https://my-elasticinstance.elastic-cloud.com"
apiKey: "mybase64apikeyhere==="
username: "Elastic"
password: "mysupersecretpassword"
port: 443
Take special note of the port. When using your own Elastic instance, this might be the standard port 9200. On Elastic Cloud, it's all routed through a reverse proxy on port 443 (https).
NOTE It's obviously never a great idea to use api keys or passwords in YML, but that's okay, to configure it from environment:
ELASTIC_ENDPOINT=host.example.com
ELASTIC_USERNAME=user@example.com
ELASTIC_PASSWORD=examplepassword
ELASTIC_API_KEY=mybase64apikeyhere===
ELASTIC_PORT=443
ELASTIC_PROTOCOL=https
And in your YML:
---
Name: MyElastic
---
Firesphere\ElasticSearch\Services\ElasticCoreService:
config:
endpoint: ENVIRONMENT
Creating an index
An index has two parts, the class and the configuration.
The most basic class would by something like the following:
<?php
namespace Firesphere\MyProject\Indexes;
use Firesphere\ElasticSearch\Indexes\ElasticIndex;
class ElasticProjectIndex extends ElasticIndex
{
public function getIndexName()
{
return 'search-indexname';
}
}
Where search-indexname
is the name of the index you've chosen when configuring it in Elastic.
The accompanying YML that configures the fields would potentially look like this:
Firesphere\ElasticSearch\Indexes\ElasticIndex:
search-indexname:
Classes:
- Page
FulltextFields:
- Title
- Content
- Description
- getElementsForSearch
- Impression.Title
FilterFields:
- OwnerID
FacetFields:
Firesphere\MyProject\Models\Tag:
BaseClass: Page
Field: Tags.ID
Title: Tag
This would at index time add those related fields in to the index, as well as at search runtime ensure all the fields are properly added as filters, where needed.
Further configuration
Please refer to the Solr documentation, and take the YML there as a guideline for configuring Elastic.
The goal is to have a near-identical API, which is largely the case already.
Creating a search
In a controller of choice, here is an example of a search:
class MyController extends PageController
{
public function search()
{
$query = $this->getRequest()->getVars();
if (isset($query['query'])) {
$baseQuery = new ElasticQuery();
// Add the term
$baseQuery->addTerm($query['query']);
// Ensure to start at 0
$start = isset($query['start']) ? $query['start'] : 0;
$baseQuery->setStart($start);
// Get the index
$index = new ElasticProjectIndex();
// And do the search
$this->Results = $index->doSearch($baseQuery);
}
return $this;
}
}
Permissions
As with the Solr search, all documents are indexed with a ViewStatus
field.
This field determines who can see the results. At search runtime, the value is calculated based on the current user
and as such passed in as an extra, required, filter.
Further functionality
Done(~ish)
- [x] Basic filtering
- [x] Pagination
- [x] Actually, you know... search
- [x] Highlighting~ish
- [x] Synonyms
- [x] Group-access filtering (e.g. all, administrators, specific groups, from access setting in the CMS)
- [x] Boosting
- [x] Faceting
- [x] Spellchecking
- [x] Unit tests and integration tests
On the to-do list is:
- [ ] Work out the filtering better
- [ ] File content searching
- [ ] Submodules for
- [ ] Member level permissions
- [ ] Subsites
- [ ] Fluent
License
Cow?
Cow!
/( ,,,,, )\
_\,;;;;;;;,/_
.-"; ;;;;;;;;; ;"-.
'.__/`_ / \ _`\__.'
| (')| |(') |
| .--' '--. |
|/ o o \|
| |
/ \ _..=.._ / \
/:. '._____.' \
;::' / \ .;
| _|_ _|_ ::|
.-| '==o==' '|-.
/ | . / \ | \
| | ::| | | .|
| ( ') (. )::|
|: | |; U U ;|:: | `|
|' | | \ U U / |' | |
##V| |_/`"""`\_| |V##
##V## ##V##
Sponsors
// @todo Firesphere needs to get some sponsor logos (And maybe some sponsors?)