A first-party PHP client for the Elastic Site Search API.

Contents

• Getting started
• Usage
• Development
• FAQ
• Contribute
• License

---

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 :

Param name	Description	Documentation URL
per_page and page	Control pagination.	https://swiftype.com/documentation/site-search/searching/pagination
document_types	Searched document types.	https://swiftype.com/documentation/site-search/searching/documenttypes
filters	Search filters	https://swiftype.com/documentation/site-search/searching/filtering
facets	Search facets.	https://swiftype.com/documentation/site-search/searching/faceting
boosts	Search boosts.	https://swiftype.com/documentation/site-search/searching/boosting
fetch_fields	Fields returned by the search.	https://swiftype.com/documentation/site-search/searching/fetch-fields
search_fields	Field (weighted) used by the search.	https://swiftype.com/documentation/site-search/searching/field-weights
highlight_fields	Field highlighting configuration.	https://swiftype.com/documentation/site-search/searching/highlight-fields
sort_field and sort_direction	Result sort order configuration	https://swiftype.com/documentation/site-search/searching/sorting
spelling	Control over the spellchecker behavior.	https://swiftype.com/documentation/site-search/searching/spelling

Clients methods

Method	Description	Documentation
asyncCreateOrUpdateDocuments	Async bulk creation or update of documents in an engine. Parameters : - $engineName (required) - $documentTypeId (required) - $documents (required)	Endpoint Documentation
createDocument	Create a new document in an engine. Parameters : - $engineName (required) - $documentTypeId (required) - $documentExternalId (required) - $documentFields (required)	Endpoint Documentation
createDocumentType	Create a new document type in an engine. Parameters : - $engineName (required) - $documentTypeName (required)	Endpoint Documentation
createDocuments	Bulk creation of documents in an engine. Parameters : - $engineName (required) - $documentTypeId (required) - $documents (required)	Endpoint Documentation
createEngine	Create a new API based engine. Parameters : - $engineName (required) - $engineLanguage	Endpoint Documentation
createOrUpdateDocument	Create or update a document in an engine. Parameters : - $engineName (required) - $documentTypeId (required) - $documentExternalId (required) - $documentFields (required)	Endpoint Documentation
createOrUpdateDocuments	Bulk creation or update of documents in an engine. Parameters : - $engineName (required) - $documentTypeId (required) - $documents (required)	Endpoint Documentation
deleteDocument	Delete a document from the engine. Parameters : - $engineName (required) - $documentTypeId (required) - $externalId (required)	Endpoint Documentation
deleteDocumentType	Delete a document type by id. Parameters : - $engineName (required) - $documentTypeId (required)	Endpoint Documentation
deleteDocuments	Bulk delete of documents in an engine. Parameters : - $engineName (required) - $documentTypeId (required) - $documents (required)	Endpoint Documentation
deleteEngine	Delete an engine by name. Parameters : - $engineName (required)	Endpoint Documentation
getAutoselectsCountAnalyticsDocumentType	Retrieve number of autoselects (number of clicked results in the autocomplete) per day over a period for a document type. Parameters : - $engineName (required) - $documentTypeId (required) - $startDate - $endDate	Endpoint Documentation
getAutoselectsCountAnalyticsEngine	Retrieve number of autoselects (number of clicked results in the autocomplete) per day over a period for an engine. Parameters : - $engineName (required) - $startDate - $endDate	Endpoint Documentation
getClicksCountAnalyticsDocumentType	Retrieve number of clicks per day over a period for a document type. Parameters : - $engineName (required) - $documentTypeId (required) - $startDate - $endDate	Endpoint Documentation
getClicksCountAnalyticsEngine	Retrieve number of clicks per day over a period for an engine. Parameters : - $engineName (required) - $startDate - $endDate	Endpoint Documentation
getDocument	Retrieve a document from the engine. Parameters : - $engineName (required) - $documentTypeId (required) - $externalId (required)	Endpoint Documentation
getDocumentReceipts	Check the status of document receipts issued by aync bulk indexing. Parameters : - $receiptIds (required)	Endpoint Documentation
getDocumentType	Get a document type by id. Parameters : - $engineName (required) - $documentTypeId (required)	Endpoint Documentation
getEngine	Retrieves an engine by name. Parameters : - $engineName (required)	Endpoint Documentation
getSearchCountAnalyticsDocumentType	Get the number of searches per day for an document type. Parameters : - $engineName (required) - $documentTypeId (required) - $startDate - $endDate	Endpoint Documentation
getSearchCountAnalyticsEngine	Get the number of searches per day for an engine. Parameters : - $engineName (required) - $startDate - $endDate	Endpoint Documentation
getTopNoResultQueriesAnalyticsDocumentType	Retrieve top queries with no result and usage count over a period for a document type. Parameters : - $engineName (required) - $documentTypeId (required) - $startDate - $endDate - $currentPage - $pageSize	Endpoint Documentation
getTopNoResultQueriesAnalyticsEngine	Retrieve top queries with no result and usage count over a period for an engine. Parameters : - $engineName (required) - $startDate - $endDate - $currentPage - $pageSize	Endpoint Documentation
getTopQueriesAnalyticsDocumentType	Retrieve top queries and usage count over a period for a document type. Parameters : - $engineName (required) - $documentTypeId (required) - $startDate - $endDate - $currentPage - $pageSize	Endpoint Documentation
getTopQueriesAnalyticsEngine	Retrieve top queries and usage count over a period for an engine. Parameters : - $engineName (required) - $startDate - $endDate - $currentPage - $pageSize	Endpoint Documentation
listDocumentTypes	List all document types for an engine. Parameters : - $engineName (required)	Endpoint Documentation
listDocuments	List all documents in an engine. Parameters : - $engineName (required) - $documentTypeId (required)	Endpoint Documentation
listEngines	Retrieves all engines with optional pagination support. Parameters : - $currentPage - $pageSize	Endpoint Documentation
logClickthrough	Record a clickthrough for a particular result. Parameters : - $engineName (required) - $documentTypeId (required) - $documentId (required) - $queryText (required)	Endpoint Documentation
search	Run a search request accross an engine. Parameters : - $engineName (required) - $queryText (required) - $searchRequestParams	Endpoint Documentation
suggest	Run an autocomplete search request accross an engine. Parameters : - $engineName (required) - $queryText (required) - $searchRequestParams	Endpoint Documentation
updateDocumentFields	Update fields of a document. Parameters : - $engineName (required) - $documentTypeId (required) - $externalId (required) - $fields (required)	Endpoint Documentation
updateDocuments	Bulk update of documents in an engine. Parameters : - $engineName (required) - $documentTypeId (required) - $documents (required)	Endpoint Documentation

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 📗

Apache 2.0 © Elastic

Thank you to all the contributors!