README

0. About

PHP package to connect to Spire SE, a semantic search engine currently in development : https://spire-se.eu

Source code : https://gitlab.com/spire-se/integration/connectors/spire-php-connector

Packagist page : https://packagist.org/packages/spire-se/spire-php-connector

1. Installation

composer require spire-se/spire-php-connector

2. Usage

A single search engine instance will handle different independent domains (realms), each with their own users, documents, data and configuration.

2.1. Connector setup

use SpireSe\SpirePhpConnector\SpireSeConnector;

$connector = new SpireSeConnector('<api endpoint>', '<personal token>', '<realm>');

Only the API endpoint is required at setup, but the majority of interactions with the API is for a specific realm, and will throw a missing configuration error on call if this is not set up properly. Similarly, some functionalities require a specific user role, and will require a personal token to identify the user.

2.2. Callers overview

Each type of interaction (search, documents, configuration, ...) uses a specific caller on which the call methods are declared.

$connector->account();
$connector->documents();
$connector->search();

As an example, to get the search results from a query string :

use GuzzleHttp\Exception\GuzzleException;
use SpireSe\SpirePhpConnector\Exceptions\ConfigNotSetUpException;
use SpireSe\SpirePhpConnector\Exceptions\SpireEndpointException;
use SpireSe\SpirePhpConnector\SpireSeConnector;

$connector = new SpireSeConnector('<api endpoint>', '<personal token>', '<realm>');

try {
    $searchResults = $connector->search()->getResultsFromQuery('<query>');
    // handle results
} catch (GuzzleException | ConfigNotSetUpException | SpireEndpointException $e) {
    // handle errors
}

2.3. Documents

To be searched, documents have to be created and indexed on the search engine first. The file is not stored on the engine itself, but an encrypted copy of the text content can be, to speed up an eventual future indexation.

2.3.1. Create and index a document

To be created, an object implementing FileDataGenerator must be passed. Raw (text files), Markdown and Pdf file can be indexed.

use SpireSe\SpirePhpConnector\SpireSeConnector;
use SpireSe\SpirePhpConnector\Contracts\FileDataGenerator;

class CustomFileData implements FileDataGenerator
{
    // Adapt uri, url and external id getters to your app file logic
}

$connector = new SpireSeConnector(...);
$fd = new CustomFileData(...);
$fileContent = ...

$connector->documents()->createFromFileData($fd);
$connector->docIndexer()->raw($fd, $fileContent);

2.3.2. Retrieve documents

use SpireSe\SpirePhpConnector\Helpers\Preload;
use SpireSe\SpirePhpConnector\SpireSeConnector;

$connector = new SpireSeConnector(...);

$documents = $connector->documents()->getAll();
$documents = $connector->documents()->getOneById(5);

// Preload : No object field is pre-loaded by default, each needed field has to be specified
$documents = $connector->documents()->getOneById(5, Preload::$Flags['language']);
$documents = $connector->documents()->getAll(Preload::$Flags['tag'] | Preload::$Flags['reference']);

// Limits and pages
$documents = $connector->documents()->getAll(0, 10); // Get 10 documents
$documents = $connector->documents()->getAll(0, 10, 2); // Get 10 documents, after the 20 first ones

2.3.2. Delete a document

use SpireSe\SpirePhpConnector\SpireSeConnector;

$connector = new SpireSeConnector(...);

$connector->documents()->delete(4);
$connector->documents()->deleteByExtId('custEdm:5a48:248b41');

2.3.3. Full example : create, index, fetch and delete a document

Click to expand

```php use GuzzleHttp\Exception\GuzzleException; use SpireSe\SpirePhpConnector\Contracts\FileDataGenerator; use SpireSe\SpirePhpConnector\Exceptions\ConfigNotSetUpException; use SpireSe\SpirePhpConnector\Exceptions\SpireEndpointException; use SpireSe\SpirePhpConnector\Helpers\Preload; use SpireSe\SpirePhpConnector\SpireSeConnector; class CustomFileData implements FileDataGenerator { public string $title; public string $url; public function __construct(string $title, string $url) { $this->title = $title; $this->url = $url; } public function getTitle(): string { return $this->title; } public function getUri(): string { return $this->getUrl(); } public function getUrl(): string { return $this->url; } public function getExternalId(): string { return sprintf('my-custom-app:%s', $this->title); } } $connector = new SpireSeConnector('', '', ''); $fd = new CustomFileData('my_document', 'myapp.local/my_document.pdf'); $fileContent = file_get_contents('./my_document.pdf'); try { $connector->documents()->createFromFileData($fd); $connector->docIndexer()->pdf($fd, $fileContent); $documents = $connector->documents()->getAll(Preload::$Flags['reference']); var_dump($documents); $connector->documents()->deleteByExtId($fd->getExternalId()); } catch (GuzzleException | ConfigNotSetUpException | SpireEndpointException $e) { // handle errors } ```

2.4 Search

Documents can be searched either by a specific item id, or directly by a string query, or. For the first option, a first step is to provide the user with an auto complete, and make them select the requested term (which is linked to an item) from a list.

2.4.1 Auto-complete

use SpireSe\SpirePhpConnector\SpireSeConnector;

$connector = new SpireSeConnector(...);

$terms = $connector->search()->getAutocompleteForQuery('<query>');

2.4.2 Querying

use SpireSe\SpirePhpConnector\SpireSeConnector;

$connector = new SpireSeConnector(...);

$results = $connector->search()->getResultsFromQuery('<query>');
$results = $connector->search()->getResultsFromItemId(10);

spire-se / spire-php-connector

Package info

Security

Statistics