README

A modular PHP client library for hlquery, designed with a familiar and intuitive API structure.

What is the hlquery PHP API?

The hlquery PHP API is the official PHP client for hlquery. It gives PHP applications a straightforward way to talk to the search engine through a small client instead of manually assembling curl calls and JSON payloads.

The library wraps hlquery's HTTP endpoints in a service-based API so you can create collections, index documents, run searches, manage lexical resources, query SAM, and call custom module routes from normal PHP code.

Why use it?

Use the PHP API when you want hlquery integration to feel like part of your application instead of a pile of hand-written REST calls. It reduces boilerplate, keeps authentication and request formatting consistent, and makes common operations easier to read and maintain.

Why choose it over raw HTTP?

Choose the PHP client over raw HTTP when you want less boilerplate around search, indexing, and admin operations, one consistent client for auth, params, headers, and response parsing, and direct access to collections, documents, SQL, overrides, synonyms, stopwords, and SAM. It also works in plain PHP with no framework requirement.

Install

Requirements:

• PHP >= 7.0
• ext-curl
• ext-json

Composer:

composer require hlquery/php-client

Local usage:

require_once __DIR__ . '/lib/autoload.php';

use Hlquery\Client;
$client = new Client(getenv('HLQ_BASE_URL') ?: (getenv('HLQUERY_BASE_URL') ?: 'http://localhost:9200'));

Composer usage:

require_once __DIR__ . '/vendor/autoload.php';

use Hlquery\Client;

$client = new Client('http://localhost:9200');

Auth

$client = new Client('http://localhost:9200', [
    'token' => 'your_token_here',
    'auth_method' => 'bearer',
]);

$client->setAuthToken('your_token_here', 'bearer');
$client->setAuthToken('your_api_key_here', 'api-key');

Quick Start

require_once __DIR__ . '/vendor/autoload.php';

use Hlquery\Client;

$client = new Client('http://localhost:9200');

$health = $client->health();
if ($health->isSuccess()) {
    echo "status: " . (($health->getBody()['status'] ?? 'ok')) . PHP_EOL;
}

$collections = $client->listCollections(0, 10);
print_r($collections->getBody());

Collections

List collections with pagination and iterate over the result:

$response = $client->listCollections(0, 100);

if (!$response->isSuccess()) {
    throw new RuntimeException('Failed to list collections: ' . $response->getStatusCode());
}

$body = $response->getBody();
$collections = $body['collections'] ?? [];

foreach ($collections as $collection) {
    $name = is_array($collection) ? ($collection['name'] ?? '') : $collection;

    if ($name === '') {
        continue;
    }

    echo $name . PHP_EOL;
}

SAM

The PHP client exposes all current SAM endpoints through Client::sam():

• search($collectionName, $query, $params = []) calls GET /sam/search.
• status($collectionName = null, $params = []) calls GET /sam/status.
• history($collectionName = null, $limit = 100, $params = []) calls GET /sam/history.

Use the SAM service for search, background status, and recent query history:

SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.

$sam = $client->sam();

$status = $sam->status('music');
$history = $sam->history('music', 5);
$results = $sam->search('music', 'queen of pop', [
    'limit' => 10,
]);

print_r($status->getBody());
print_r($history->getBody());
print_r($results->getBody());

SQL

$sql = $client->sql();

$rows = $sql->query('SHOW COLLECTIONS;');
$books = $sql->search(
    'books',
    'SELECT id, title FROM books ORDER BY title ASC LIMIT 3;'
);

print_r($rows->getBody());
print_r($books->getBody());

Reduce Text Example

Use executeRequest() to call custom module routes directly:

$moduleResponse = $client->executeRequest('GET', '/modules/<name>/<route>', null, [
    'q' => 'example query',
]);

print_r($moduleResponse->getBody());