openeuropa/europa-search-client

A PHP client library for communicating with the Europa Search service.

1.0.0-alpha8 2024-09-02 10:38 UTC

Requires

• php: >=8.0
• ext-fileinfo: *
• ext-json: *
• league/container: ^3.3 || ^4.2
• php-http/multipart-stream-builder: ^1.1
• phpdocumentor/reflection-docblock: ^5.2
• phpdocumentor/type-resolver: ^1.4
• psr/http-client: ^1.0
• psr/http-client-implementation: *
• psr/http-factory: ^1.0
• psr/http-factory-implementation: *
• symfony/options-resolver: ^4.4.30 || ^5 || ^6.2
• symfony/property-access: ^4.4 || ^6.2
• symfony/property-info: ^4.4 || ^6.2
• symfony/serializer: ^4.4 || ^6.2

Requires (Dev)

• guzzlehttp/guzzle: ^7
• guzzlehttp/psr7: ^2
• openeuropa/code-review: ^2.0.0-alpha6
• phpunit/phpunit: ^9.4

Suggests

• guzzlehttp/guzzle: PSR-18 HTTP Client implementation
• guzzlehttp/psr7: PSR-17 HTTP Factories implementation

EUPL-1.2

README

Description

Europa Search Client is a library offering a PHP API to consume Europa Search services.

Install

Use Composer to install the package:

$ composer require openeuropa/europa-search-client

Usage

All calls should be done by instantiating the client class:

require_once 'vendor/autoload.php';

$client = new \OpenEuropa\EuropaSearchClient\Client(
    new \GuzzleHttp\Client(),
    new \Http\Factory\Guzzle\RequestFactory(),
    new \Http\Factory\Guzzle\StreamFactory(),
    new \Http\Factory\Guzzle\UriFactory(),
    [
        // For a full list of options see "Configuration".
        'apiKey' => 'foo',
        'searchApiEndpoint' => 'https://example.com/search',
    ]
);

In the above example, we're passing the Guzzle HTTP client, request, stream and URI factories. But these can be replaced by any similar factories that are implementing the PSR interfaces. The last parameter is the configuration.

Configuration

Possible configurations:

• apiKey (string): Used by the Search and Ingestion APIs.
• database (string): Used by Ingestion API.
• infoApiEndpoint (string, valid URI): The Search API info endpoint.
• searchApiEndpoint (string, valid URI): The Search API endpoint.
• facetApiEndpoint (string, valid URI): The Search API facets endpoint.
• tokenApiEndpoint (string, valid URI): The endpoint for Authorisation/Token API.
• consumerKey (string): Used by Authorisation/Token API.
• consumerSecret (string): Used by Authorisation/Token API.
• textIngestionApiEndpoint (string, valid URI): The Ingestion API endpoint to ingest text.
• fileIngestionApiEndpoint (string, valid URI): The Ingestion API endpoint to ingest files.
• deleteApiEndpoint (string, valid URI): The Ingestion API endpoint to delete a document from the index.

Server info

$response = $client->getInfo();

Will return information about Europa Search server availability and API version.

Searching

Simple

$response = $client->search('something to search');

The search can be fine-tuned by passing additional arguments. Check \OpenEuropa\EuropaSearchClient\Contract\ClientInterface::search() for a full list of parameters. The response is an \OpenEuropa\EuropaSearchClient\Model\Search object.

Facets

$response = $client->getFacets('something to search');

The facets search can be fine-tuned by passing additional arguments. Check \OpenEuropa\EuropaSearchClient\Contract\ClientInterface::getFacets() for a full list of parameters. The response is an \OpenEuropa\EuropaSearchClient\Model\Facets object.

Ingesting

Text

$response = $client->ingestText('http://example.com/page/to/be/ingested', 'text to be ingested/index');

Check \OpenEuropa\EuropaSearchClient\Contract\ClientInterface::ingestText() for a complete list of parameters. The response is an \OpenEuropa\EuropaSearchClient\Model\Ingestion object.

File

$binaryString = file_get_contents(...);
$client->ingestFile('http://example.com/file/to/be/ingested', $binaryString);

Check \OpenEuropa\EuropaSearchClient\Contract\ClientInterface::ingestFile() for a complete list of parameters. The response is an \OpenEuropa\EuropaSearchClient\Model\Ingestion object.

Delete document

$success = $client->deleteDocument('referenceID');

The function returns a boolean indicating if the operation was successful.

Contributing

Please read the full documentation for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning.