elastic / enterprise-search-php

Elastic Enterprise Search Official PHP Client

Elastic Enterprise Search Client for PHP

A first-party PHP client to interface with Elastic Enterpise Search including Elastic App Search and Elastic Workplace Search.

Installation

The package can be installed using composer:

composer require elastic/enterprise-search

The version follows the Elastic Stack version so 8.0 is compatible with Enterprise Search released in Elastic Stack 8.0.

PSR-18 HTTP library

This project uses elastic-transport-php as HTTP library. This is a component that abstracts the usage of any PSR-18 client libraries. It uses the autodiscovery feature of HTTPlug to find a compliant library already installed in your vendor. If you receive an error like No PSR-18 clients found this means you don't have any PSR-18 library installed. We suggest to use Guzzle v7+ as HTTP library. You can require it using composer:

composer require guzzlehttp/guzzle

If you want to be sure to use a specific HTTP library you need to pass it in the Client constructor, as follows:

use Elastic\EnterpriseSearch\Client;

$client = new Client([
    'client' => new GuzzleHttp\Client,
   // ...
]);

Guzzle v6

If you want to use Guzzle v6, you need to add the php-http/guzzle6-adapter as composer requirement.

Documentation

See the documentation for how to get started, compatibility info, configuring, and an API reference.

Contributing

If you'd like to make a contribution to enterprise-search-php we provide contributing documentation to ensure your first contribution goes smoothly.

License

enterprise-search-php is available under the MIT license. For more details see LICENSE.

enterprise-search-php's Issues

Keep null values in serialized body when indexing

Hi,

We're considering switching from deprecated elastic/app-search-php to elastic/enterprise-search-php.
However, I found a strange behavioural choice that I don't understand and you might be able to help me figure it out.

When indexing documents, we must use an IndexDocuments request, requiring as second argument an array of Document.
It works well, except with nullable fields. If the field as no value, we can't index this field as it is automatically removed from request at serialization time: https://github.com/elastic/enterprise-search-php/blob/master/src/Request/Request.php#L90.

We can't bypass that as serializers are not configurable, and body in IndexDocuments could not accept anything other than an array.

Why would you remove prevent nullable fields from indexing ?

Let's imagine that you have order data to index, that has multiple fields, including creationDate and deliveryDate.
deliveryDate is nullable when the order is not yet delivered.
As you can't index deliveryDate field, it is not present in the document response, and you could not filter results having null deliveryDate, right ?

Is it a bad practice to index nullable fields having null value ? If not, would it be possible to allow indexing of null values ?

Thank you.

[Request feedback] Looking for feedback about the UX experience

The engineering team here at Elastic is looking for developers to participate in research and feedback sessions to learn more about how you use our PHP client and what improvements we can make to their design and your workflow. If you're interested in sharing your insights into developer experience and language client design, please fill out this short form. Depending on the number of responses we get, we may either contact you for a 1:1 conversation or a focus group with other developers who use the same client. Thank you in advance - your feedback is crucial to improving the user experience for all Elasticsearch developers!

Getting error 500 when I'm trying to connect to enterprise-search

Hi, first of all, thank you for creating such amazing tools and make search engine always more powerfull.

When I enter my login and password into the client, as mentionned into the "Get started" section of the documentation, I get a 500 internal error and nothing shows up on my screen when my code is executed.

Does this issue is related to the fact that I run app-search v7.13.2 and the php client is v7.13.0 ? If yes, do I need to downgrade my elasticsearch and app-search to 7.13.0 too ?

Thank you

Weird results when searching a specific item

Hello,

I have a search bar where customers can search for items. It works pretty well except for one thing and I don't figure out why.

Context : When I search dynasam, the engine is returning me items that don't fit with my search query. When i'm adding a "®" which correspond to the exact term, I then get the results I want. Even when I'm trying in the query tester, I get weird results as long as I don't add the "®". Also, I have tuned my precision to 2 in the search API.
Do you have any idea/advices why it happens ? (I also tried to add some synonyms sets but nothing has changed).
Thank you, best regards
Nagib

Document class not found in AppSearch/Request namespace

Hi,

I'm fairly new to AppSearch and found this library to help me setting up my calls to our APIs
I'm in charge to index files in our engine so i used the AppSearch\Request\IndexDocuments class that looks like this :

/**
 * Elastic Enterprise Search
 *
 * @link      https://github.com/elastic/enterprise-search-php
 * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
 * @license   https://opensource.org/licenses/MIT MIT License
 *
 * Licensed to Elasticsearch B.V under one or more agreements.
 * Elasticsearch B.V licenses this file to you under the MIT License.
 * See the LICENSE file in the project root for more information.
 */

declare(strict_types=1);

namespace Elastic\EnterpriseSearch\AppSearch\Request;

use Elastic\EnterpriseSearch\Request\Request;

/**
 * Create a new document
 *
 * @see https://www.elastic.co/guide/en/app-search/current/documents.html#documents-create
 * @generated This file is generated, please do not edit
 */
class IndexDocuments extends Request
{
	/**
	 * @param string $engineName Name of the engine
	 * @param Document[] $documents
	 */
	public function __construct(string $engineName, array $documents = null)
	{
		$this->method = 'POST';
		$engine_name = urlencode($engineName);
		$this->path = "/api/as/v1/engines/$engine_name/documents";
		$this->headers['Content-Type'] = 'application/json';
		$this->body = $documents;
	}
}

In the param section, it says it uses a Document[] array to send them. I used the "AppSearch\Schema\Document" class to index my documents but since there isn't any "use " of this class in the IndexDocuments class, it looks for an "AppSearch\Request\Document" class that does not exist.
It works as expected (i can actually send the documents) but quality code fails (also PHPStorm triggers a warning) so maybe adding the proper "use" should be able to fix this ?

Or maybe i'm totally wrong somewhere and you can help me :)

Also : I use the 8.4 version

Stable 8 release

Would be awesome with a stable 8 release. We've already prepared our move to App Search 8 and just waiting for a stable 8 release before pressing the go button.

Incorrect query params

We're having problems fetching any other page than the default page for the list engine operation with the last published version.

Looking at the code, it looks like the query_params are incorrect on some release branches:
https://github.com/elastic/enterprise-search-php/blob/7.15/src/AppSearch/Request/ListEngines.php

While the code on the master branch uses the correct query_params:
https://github.com/elastic/enterprise-search-php/blob/master/src/AppSearch/Request/ListEngines.php

And one of the older releases uses the correct query_params as well:
https://github.com/elastic/enterprise-search-php/blob/7.14/src/AppSearch/Request/ListEngines.php

Relevant documentation: https://www.elastic.co/guide/en/app-search/7.15/engines.html#engines-query-list

Classes are marked as internal

Hey team,

It seems like the expectation for using this library is to use the classes to create requests like so:

$client = new Client(...args);
$result = $client->getAppSearch()
                            ->getSchema(new GetSchema('env'));

The above getAppSearch returns an instance of AppEndpoints which is marked as internal. Then GetSchema is marked as internal too.

If these are marked as internal then my assumption is to not use them as they are internal classes for the SDK. However, there's no way to use the SDK without these classes.

Implement the createSignedSearchKey feature

Implement the createSignedSearchKey feature specified here and discudded in this blog post. This feature is already implemented in enterprise-search-python and enterprise-search-ruby.

Not a valid Json: Control character error, possibly incorrectly encode

I am getting an error from the response from this code:

$engineName = 'videogames';

// Single Search
$search = new Schema\SearchRequestParams('luigi');

$result = $this->appSearch->search(
new Request\Search($engineName, $search)
);
print_r($result->asArray()); // this is where the error is caught

any help would be appreciated.

putSchema is not available

I'm trying to update the schema using the PutSchema but the SchemaUpdateRequest class is empty and the PutSchema is required to use the SchemaUpdateRequest as a second paramater.

So there is no way that you can update the schema. Or is there another way?

Incorrect property name

The SearchRequestParams class in AppSearch has a property called boost which I think should be called boosts.

If you attempt to build a query using boost you will get an invalid key error. The API wants boosts.

$params->boosts = new Schema\SearchBoosts();
....
//works

compare to

$params->boost = new Schema\SearchBoosts();
...
//does not work

Request with proxy

Hi,

I need to create an EnterpriseSearch client with a proxy configuration but I didn't find any mention of how can i add proxy to the client.

Can you help me please ?

Dynamic properties issue

Since 8.2 dynamic properties are deprecated (https://wiki.php.net/rfc/deprecate_dynamic_properties) and from 9.0 it will throw error.
Prehaps it's good point to consider publishing OAS?

Error: This API action is not available for Engines based on an Elasticsearch index

I am using the Drupal module elastic_enterprise_search and am connected to an Elastic cloud instance which is running its own engine.

When I attempt to reindex content, the API returns Error 400 Bad Request from src/AppSearch/Endpoints.php

However, via the console, I was able to get a more specific error message.

What causes this error and is there any configuration I can do to resolve it?

How to limit result fields ?

Hello,
I can't figure how to use the result_fields of the SearchRequestParams.

Here's what i do :

$client = new Client([
	'host' => ELASTIC_API_ENDPOINT,
	'apiKey' => ELASTIC_API_TOKEN,
	'logger' => $logger,
]);
$appSearch = $client->appSearch();
$search = new SearchRequestParams($term);
$search->page = new PaginationResponseObject();
$search->page->size = ($max_results ?: 25);
$search->result_fields = new SimpleObject();
$search->result_fields->body_content = 'raw';
$request = new Request\Search($engine, $search);
$searchResults = $appSearch->search($request)->asArray();

Request body :

{"query":"testing","page":{"size":25},"result_fields":{"body_content":"raw"}}

Error 400, response body :

{"errors":["Result fields contains invalid value for field: body_content; must be an object"]}

Without result_fields, everything works fine.

Is it me or is there a problem with result_fields ?

Thanx,

PHP 8.1 support

Can you please add php 8.1 support:

Fatal error: During inheritance of ArrayAccess: Uncaught Exception: Deprecated Functionality: Return type of Elastic\EnterpriseSearch\Response\Response::offsetGet($offset) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice

Weird decoding of HTTP response

We've been using an old AppSearch PHP library until now. It worked fine but we decided to update it. When we copied a basic code from examples, we got some errors because of JSON parsing. When we're parsing response as string, we got a bunch of un-encoded bytes. I get some request details when I printed result (ex. new Client(...)->appSearch()->search(...); ). Request details says that response is compressed as GZIP (content-encoding: gzip). Once I decode these bytes, I successfully get normal JSON. Unfortunately, I can't find any settings about compressing a content in configurations of elastic or enterprise-search, but I believe that this is problem not only to us. I think library should decrypt content, if needed, before parsing it. And, how it mentioned before, it somehow worked and working now successfully in old AppSearch library.

Nullable parameters in PHP generated classes

Some generated the Schema classes have the nullable option (?) in constructor but they don't have nullable in the property definition. For instance, the ExtractUrlIndexingResults in AppSearch\Schema :

namespace Elastic\EnterpriseSearch\AppSearch\Schema;

/**
 * @generated This file is generated, please do not edit
 */
class ExtractUrlIndexingResults
{
	public string $document_id;
	public object $document_fields;


	public function __construct(?string $document_id, ?object $document_fields)
	{
		$this->document_id = $document_id;
		$this->document_fields = $document_fields;
	}
}

In this example, the $document_id and the $document_fields properties will generate a FATAL error when set to null.
The FATAL error at runtime will be PHP Fatal error: Uncaught TypeError: Cannot assign null to property.
We need to fix this adding nullable also in the definition, as follows:

namespace Elastic\EnterpriseSearch\AppSearch\Schema;

/**
 * @generated This file is generated, please do not edit
 */
class ExtractUrlIndexingResults
{
	public ?string $document_id;
	public ?object $document_fields;


	public function __construct(?string $document_id, ?object $document_fields)
	{
		$this->document_id = $document_id;
		$this->document_fields = $document_fields;
	}
}

Allow Document Creation Without Id

Can the Document class be updated to allow not passing in an id so that elasticsearch can create a unique one on index?

According to the documentation documents can be created without needing to pass in an id.

Sometimes you don't have a source for an id and just need elasticsearch to generate a unique one when indexing.

No PSR-18 clients found. Make sure to install a package providing "psr/http-client-implementation"

Summary of problem or feature request

We've upgraded our Dev Elastic deployment to 8.4 and in the process of looking at whether our service implementation needs an update.

Looking through the documentation it appears not but I'm getting

Http\Discovery\Exception\NotFoundException: No PSR-18 clients found. Make sure to install a package providing "psr/http-client-implementation". Example: "php-http/guzzle7-adapter". in Http\Discovery\Psr18ClientDiscovery::find() (line 27 of /var/www/html/vendor/php-http/discovery/src/Psr18ClientDiscovery.php).

There seems to be no mention of this in the App Search docs. I even installed with dependencies.

Code snippet of problem

 protected function connect(): void {
    $elastic_client = new Client([
      'host' => $this->getApplicationHost(),
      'app-search' => [
        'token' => $this->getApiToken(),
      ],
    ]);

    $this->appSearch = $elastic_client->appSearch();
  }

System details

• PHP Version 8.0
• ES-PHP client version 8.4
• Elasticsearch version 8.4

Guzzle

Hey guys,

is it possible to support guzzle 6 for both (elastic/transport)?

thx

PHP 8.1: Deprecation notices for Response / ArrayAccess

The definition of the ArrayAccess::offsetGet() has changed in PHP 8.1 to add the (new) mixed return type:

interface ArrayAccess {
    public offsetExists(mixed $offset): bool

    /**
     * new (): mixed
     */
    public offsetGet(mixed $offset): mixed

    public offsetSet(mixed $offset, mixed $value): void

    public offsetUnset(mixed $offset): void
}

This results in the following deprecation error being thrown:

PHP Deprecated:  Return type of Elastic\EnterpriseSearch\Response\Response::offsetGet($offset) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /var/www/mysite/www/vendor/elastic/enterprise-search/src/Response/Response.php on line 194

This project supports PHP 7.4, 8.0, and 8.1. As such, I believe the only option would be for us to add the attribute for #[\ReturnTypeWillChange].

I hope to have a pull request up shortly 😃

AppSearch how to use sort?

I cannot figure out how to assing correct SimpleObject in SearchRequestParams to sort results by e.g. fieldA and then fieldB.
In previous package versions it wasn't type-hinted property so I could do something like this:
$searchRequestParams->sort = [['fieldA' => 'desc'], ['fieldB' => 'desc']];
But now it's type-hinted property so I can't do this.

Is it possible to provide OAS for enterprise search or OAS isn't flexible enough?

Function setTags in LogClickthrough seems not working

Hi, I want to implement the functionality to get a specific tag when user clicks on a link. The LogClickthrough works without setting a tag, but when I try to set a Tag, it doen't work as expected, here's my code :

$app = $client->appSearch(); $szClick = new Request\LogClickthrough($szEngine, $szSearch, $nIdDoc); $szClick->setTags(['testTag']); // Here's my attempt to put a tag on the logClickthrough response $app->logClickthrough($szClick);

I've tried different ways to get this work but none of my attempts were successfull