A first-party PHP client for building excellent, relevant search experiences with Elastic App Search.

Contents

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

---

Getting started 🐣

Using this client assumes that you have already created an App Search account on https://swiftype.com/ or you have a self managed version of App Search available.

You can install the client in your project by using composer:

composer require elastic/app-search

Versioning

This client is versioned and released alongside App Search.

To guarantee compatibility, use the most recent version of this library within the major version of the corresponding App Search implementation.

For example, for App Search 7.3, use 7.3 of this library or above, but not 8.0.

If you are a SaaS user, simply use the most recent version of this library.

Usage

Configuring the client

Basic client instantiation

To instantiate a new client you can use \Elastic\AppSearch\Client\ClientBuilder:

  $apiEndpoint   = 'http://localhost:3002/';
  $apiKey        = 'private-XXXXXXXXXXXX';
  $clientBuilder = \Elastic\AppSearch\Client\ClientBuilder::create($apiEndpoint, $apiKey);

  $client = $clientBuilder->build();

Notes:

• The resulting client will be of type \Elastic\AppSearch\Client\Client

• You can find the API endpoint and your API key URL in your App Search account: https://app.swiftype.com/as/credentials.

• You can use any type of API Key (private, public or admin). The client will throw an exception if you try to execute an action that is not authorized for the key used.

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. Set it to null to apply the universal language.

Read more about language support.

Index some documents

You can use the Client::indexDocuments method to index some documents into the Engine:

    $documents = [
      ['id' => 'first-document', 'name' => 'Document name', 'description' => 'Document description'],
      ['id' => 'other-document', 'name' => 'Other document name', 'description' => 'Other description'],
    ];

    $indexingResults = $client->indexDocuments('my-engine', $documents);

The $indexingResults array will contain the result of the indexation of each documents. You should always check the content of the result.

Read more about document indexing.

Search

You can use the Client::search method to search in your Engine:

    $searchParams = [
      'page'  => ['current' => 1, 'size' => 10]
    ];

    $searchResponse = $client->search('my-engine', 'search text', $searchParams);

If you want to match all documents you can use and empty search query '' as second parameter ($queryText).

The $searchRequestParams parameter is optional and can be used to use advanced search features. Allowed params are :

Param name	Documentation URL
page	https://swiftype.com/documentation/app-search/api/search#paging
filters	https://swiftype.com/documentation/app-search/api/search/filters
facets	https://swiftype.com/documentation/app-search/api/search/facets
sort	https://swiftype.com/documentation/app-search/api/search/sorting
boosts	https://swiftype.com/documentation/app-search/api/search/boosts
search_fields	https://swiftype.com/documentation/app-search/api/search/search-fields
result_fields	https://swiftype.com/documentation/app-search/api/search/result-fields
group	https://swiftype.com/documentation/app-search/api/search/grouping

The search response will contains at least a meta field and a results field as shown in this example:

[
    'meta' => [
      'warnings' => [],
      'page' => [
        'current' => 1,
        'total_pages' => 1,
        'total_results' => 1,
        'size' => 10
      ],
      'request_id' => 'feff7cf2359a6f6da84586969ef0ca89'
    ],
    'results' => [
      [
        'id' => ['raw' => 'first-document'],
        'name' => ['raw' => 'Document name'],
        'description' => ['raw' => ['Document description']
      ]
    ]
  ]
]

Clients methods

Method	Description	Documentation
createCuration	Create a new curation. Parameters : - $engineName (required) - $queries (required) - $promotedDocIds - $hiddenDocIds	Endpoint Documentation
createEngine	Creates a new engine. Parameters : - $name (required) - $language	Endpoint Documentation
createSynonymSet	Create a new synonym set. Parameters : - $engineName (required) - $synonyms (required)	Endpoint Documentation
deleteCuration	Delete a curation by id. Parameters : - $engineName (required) - $curationId (required)	Endpoint Documentation
deleteDocuments	Delete documents by id. Parameters : - $engineName (required) - $documentIds (required)	Endpoint Documentation
deleteEngine	Delete an engine by name. Parameters : - $engineName (required)	Endpoint Documentation
deleteSynonymSet	Delete a synonym set by id. Parameters : - $engineName (required) - $synonymSetId (required)	Endpoint Documentation
getApiLogs	The API Log displays API request and response data at the Engine level. Parameters : - $engineName (required) - $fromDate (required) - $toDate (required) - $currentPage - $pageSize - $query - $httpStatusFilter - $httpMethodFilter - $sortDirection	Endpoint Documentation
getCountAnalytics	Returns the number of clicks and total number of queries over a period. Parameters : - $engineName (required) - $filters - $interval	Endpoint Documentation
getCuration	Retrieve a curation by id. Parameters : - $engineName (required) - $curationId (required)	Endpoint Documentation
getDocuments	Retrieves one or more documents by id. Parameters : - $engineName (required) - $documentIds (required)	Endpoint Documentation
getEngine	Retrieves an engine by name. Parameters : - $engineName (required)	Endpoint Documentation
getSchema	Retrieve current schema for then engine. Parameters : - $engineName (required)	Endpoint Documentation
getSearchSettings	Retrive current search settings for the engine. Parameters : - $engineName (required)	Endpoint Documentation
getSynonymSet	Retrieve a synonym set by id. Parameters : - $engineName (required) - $synonymSetId (required)	Endpoint Documentation
getTopClicksAnalytics	Returns the number of clicks received by a document in descending order. Parameters : - $engineName (required) - $query - $pageSize - $filters	Endpoint Documentation
getTopQueriesAnalytics	Returns queries anlaytics by usage count. Parameters : - $engineName (required) - $pageSize - $filters	Endpoint Documentation
indexDocuments	Create or update documents. Parameters : - $engineName (required) - $documents (required)	Endpoint Documentation
listCurations	Retrieve available curations for the engine. Parameters : - $engineName (required) - $currentPage - $pageSize	Endpoint Documentation
listDocuments	List all available documents with optional pagination support. Parameters : - $engineName (required) - $currentPage - $pageSize	Endpoint Documentation
listEngines	Retrieves all engines with optional pagination support. Parameters : - $currentPage - $pageSize	Endpoint Documentation
listSynonymSets	Retrieve available synonym sets for the engine. Parameters : - $engineName (required) - $currentPage - $pageSize	Endpoint Documentation
logClickthrough	Send data about clicked results. Parameters : - $engineName (required) - $queryText (required) - $documentId (required) - $requestId - $tags	Endpoint Documentation
multiSearch	Run several search in the same request. Parameters : - $engineName (required) - $queries (required)	Endpoint Documentation
querySuggestion	Provide relevant query suggestions for incomplete queries. Parameters : - $engineName (required) - $query (required) - $fields - $size	Endpoint Documentation
resetSearchSettings	Reset search settings for the engine. Parameters : - $engineName (required)	Endpoint Documentation
search	Allows you to search over, facet and filter your data. Parameters : - $engineName (required) - $queryText (required) - $searchRequestParams	Endpoint Documentation
updateCuration	Update an existing curation. Parameters : - $engineName (required) - $curationId (required) - $queries (required) - $promotedDocIds - $hiddenDocIds	Endpoint Documentation
updateDocuments	Partial update of documents. Parameters : - $engineName (required) - $documents (required)	Endpoint Documentation
updateSchema	Update schema for the current engine. Parameters : - $engineName (required) - $schema (required)	Endpoint Documentation
updateSearchSettings	Update search settings for the engine. Parameters : - $engineName (required) - $searchSettings (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!