elastic / site-search-php
Elastic Site Search Official PHP Client
Installs: 908
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 19
Forks: 13
Open Issues: 1
Requires
- php: ^5.6|^7.0|^8.0
- elastic/openapi-codegen: ^1.0.6
- psr/log: ^1|^2|^3
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.19|^3.0
- overtrue/phplint: ^1.2|^2.4|^3.4|^4.0|^5.0|^6.0
- phpunit/phpunit: ^5.6.0|^6.3.0|9.5.20
- squizlabs/php_codesniffer: ^3.4.0
- symfony/yaml: *
This package is auto-updated.
Last update: 2024-08-08 15:59:30 UTC
README
A first-party PHP client for the Elastic Site Search API.
Contents
Getting started 🐣
Using this client assumes that you have already created a Site Search account on https://www.elastic.co/products/site-search.
You can install the client in your project by using composer:
composer require elastic/site-search
Usage
Configuring the client
Basic client instantiation
To instantiate a new client you can use \Elastic\SiteSearch\Client\ClientBuilder
:
$apiKey = 'XXXXXXXXXXXX'; $clientBuilder = \Elastic\SiteSearch\Client\ClientBuilder::create($apiKey); $client = $clientBuilder->build();
Notes:
-
The resulting client will be of type
\Elastic\SiteSearch\Client\Client
-
You can find the API endpoint and your API key URL in your Site Search account: https://app.swiftype.com/settings/account.
-
The Site Search PHP client does not support authentication through Engine Key as described in the documentation.
Basic usage
Retrieve or create an engine
Most methods of the API require that you have access to an Engine.
To check if an Engine exists and retrieve its configuration, you can use the Client::getEngine
method :
$engine = $client->getEngine('my-engine');
If the Engine does not exists yet, you can create it by using the Client::createEngine
method :
$engine = $client->createEngine('my-engine', 'en');
The second parameter ($language
) is optional or can be set to null. Then the Engine will be created using the universal
language.
The list of supported language is available here : https://swiftype.com/documentation/site-search/overview#language-optimization
Document types
When using Site Search every document has an associated DocumentType.
You can list available document types in an engine by using the Client::listDocumentTypes
method:
$documentTypes = $client->listDocumentTypes('my-engine');
In order to index documents you need to create at least one DocumentType in your engine. This can be done by using the Client::createDocumentType` method:
$documentType = $client->createDocumentType('my-engine', 'my-document-type');
Index some documents
In order to index some documents in the Engine you can use the Client::createOrUpdateDocuments
method:
$documents = [ [ 'external_id' => 'first-document', 'fields' => [ ['name' => 'title', 'value' => 'First document title', 'type' => 'string'], ['name' => 'content', 'value' => 'Text for the first document.', 'type' => 'string'], ] ], [ 'external_id' => 'other-document', 'fields' => [ ['name' => 'title', 'value' => 'Other document title', 'type' => 'string'], ['name' => 'content', 'value' => 'Text for the other document.', 'type' => 'string'], ] ], ]; $indexingResults = $client->createOrUpdateDocuments('my-engine', 'my-document-type', $documents);
Notes:
-
The
$indexingResults
array will contains the result of the indexation of each documents. You should always check the content of the result. -
A full list of available field types and associated use cases is available here: https://swiftype.com/documentation/site-search/overview#fieldtype
-
Full documentation for the endpoint and other method available to index documents is available here: https://swiftype.com/documentation/site-search/indexing.
Search
In order to search in your Engine you can use the Client::search
method :
$searchResponse = $client->search('my-engine', 'fulltext search query');
An optional $searchRequestParams
can be used to pass additional parameters to the Search API endpoint (pagination, filters, facets, ...):
$searchParams = ['per_page' => 10, 'page' => 2]; $searchResponse = $client->search('my-engine', 'fulltext search query', $searchParams);
Allowed params are :
Clients methods
Development
Code for the endpoints is generated automatically using a custom version of OpenAPI Generator.
To regenerate endpoints, use the docker laucher packaged in vendor/bin
:
./vendor/bin/elastic-openapi-codegen.sh
The custom generator will be built and launched using the following Open API spec file : resources/api/api-spec.yml
.
You can then commit and PR the modified api-spec file and your endpoints code files.
The client class and readme may be changed in some cases. Do not forget to include them in your commit!
FAQ 🔮
Where do I report issues with the client?
If something is not working as expected, please open an issue.
Where can I find the full API documentation ?
Your best bet is to read the documentation.
Where else can I go to get help?
You can checkout the Elastic community discuss forums.
Contribute 🚀
We welcome contributors to the project. Before you begin, a couple notes...
- Before opening a pull request, please create an issue to discuss the scope of your proposal.
- Please write simple code and concise documentation, when appropriate.
License 📗
Thank you to all the contributors!