PHP SDK

The PHP SDK is published on Packagist and the source lives on GitHub. Install it with Composer in Laravel or any other PHP app.

Installation

composer require neuronsearchlab/sdk-php

If you are using Laravel, this is the standard installation path. Composer pulls the package from Packagist automatically.

Initialize the client

The SDK uses a Bearer token for authentication. Obtain an access token by exchanging your SDK credentials and pass it when creating the client:

<?php

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

use NeuronSearchLab\NeuronSDK;

$sdk = new NeuronSDK([
    'baseUrl' => 'https://api.neuronsearchlab.com/v1',
    'accessToken' => '<your_access_token>',
]);

Configuration options

Option	Type	Default	Description
`baseUrl`	string	required	API base URL
`accessToken`	string	required	Bearer token from the auth token endpoint
`timeoutMs`	int	`10000`	HTTP request timeout in ms
`maxRetries`	int	`2`	Retry count on 429/5xx/timeouts
`collateWindowSeconds`	float	`3`	Buffer events for this many seconds before flushing
`maxBatchSize`	int	`200`	Flush immediately when the buffer reaches this size
`maxBufferedEvents`	int	`5000`	Drop oldest events beyond this limit
`maxEventRetries`	int	`5`	Retry count for buffered event sends
`disableArrayBatching`	bool	`false`	Force single-event sends
`propagateRecommendationRequestId`	bool	`true`	Auto-attach `request_id` from recommendations to subsequent events
`sessionId`	string or null	`null`	Override the SDK-wide session ID
`autoSessionId`	bool	`true`	Auto-generate a session UUID
`httpClient`	callable	cURL	Custom HTTP transport for non-cURL environments or tests

Get recommendations

$result = $sdk->getRecommendations([
    'userId' => 'user-123',
    'contextId' => '101',
    'limit' => 10,
]);

var_dump($result['recommendations']);

Each recommendation includes id, object, item_id, rank, score, and an embedded item object with the metadata you stored. The response also includes a request_id for event attribution.

Search

Use search when the user supplies a free-text query and you want ranked catalog items back through the Core API data plane:

$results = $sdk->search([
    'query' => 'waterproof trail shoes',
    'userId' => 'user-123',
    'contextId' => '101',
    'limit' => 10,
    'filter' => ['category:footwear'],
]);

var_dump($results['data']);

The SDK posts to https://api.neuronsearchlab.com/v1/search, not the console Platform API. Search responses use the same item shape as recommendations and include query, request_id, data, and recommendations.

Searches your own engine runs

Every search is an event that steers the user’s later recommendations by the weight of your Search event. If your own engine runs the search, send NSL the query and the IDs it showed:

// Record it and get recommendations that complement your results
// (the IDs you send are left out of the response).
$extras = $sdk->search([
    'query' => 'waterproof trail shoes',
    'userId' => 'user-123',
    'resultItemIds' => [3187, 3190, 3201],
]);

// Record only. eventId is optional and defaults to your Search event.
$sdk->trackSearch([
    'userId' => 'user-123',
    'query' => 'waterproof trail shoes',
    'resultItemIds' => [3187, 3190, 3201],
])->wait();

Requires neuronsearchlab/sdk-php 2.2.0 or later. See searches are events.

Auto-generated sections

Use getAutoRecommendations for paginated, auto-titled recommendation sections:

$section = $sdk->getAutoRecommendations([
    'userId' => 'user-123',
    'limit' => 5,
    'windowDays' => 7,
]);

if (!empty($section['next_cursor'])) {
    $next = $sdk->getAutoRecommendations([
        'userId' => 'user-123',
        'cursor' => $section['next_cursor'],
    ]);
}

Track events

Events provide the feedback loop that powers personalization. The PHP SDK buffers events in memory for the lifetime of the current process.

$sdk->trackEvent([
    'type' => 'click',
    'userId' => 'user-123',
    'itemId' => '7f3a2c9e',
])->wait();

How batching works in PHP

Buffer events

Events are buffered with a timestamp that maps to occurred_at in the API.

Flush at max batch size

The buffer flushes when it reaches maxBatchSize.

Force delivery when needed

You can force delivery with flushEvents() or by calling ->wait() on the returned PendingResult.

Flush during shutdown

Remaining buffered events are flushed during PHP shutdown.

Retry failed sends

Failed sends are retried with exponential backoff.

$pending = $sdk->trackEvent([
    'type' => 'view',
    'userId' => 'user-123',
    'itemId' => '7f3a2c9e',
]);

$pending->wait();

$sdk->flushEvents();

Request ID propagation

When propagateRecommendationRequestId is enabled, the SDK captures the request_id from getRecommendations() or search() and automatically attaches it to subsequent trackEvent() calls unless you explicitly provide requestId or request_id.

$recs = $sdk->getRecommendations([
    'userId' => 'user-123',
    'limit' => 5,
]);

$sdk->trackEvent([
    'type' => 'click',
    'userId' => 'user-123',
    'itemId' => $recs['recommendations'][0]['item_id'],
])->wait();

Manage catalog items

Create an item

$sdk->upsertItem([
    'itemId' => '7f3a2c9e',
    'name' => 'Nike Running Shoes',
    'description' => 'High-performance running shoes for daily training.',
    'metadata' => [
        'category' => 'Footwear',
        'brand' => 'Nike',
        'price' => 109.99,
    ],
]);

Update an item

$sdk->patchItem([
    'itemId' => '7f3a2c9e',
    'active' => false,
]);

Or use the convenience helper:

$sdk->setItemActive('7f3a2c9e', false);

Delete items

$sdk->deleteItems(['itemId' => '7f3a2c9e']);

$sdk->deleteItems([
    ['itemId' => '7f3a2c9e'],
    ['itemId' => 'a8d1b247'],
]);

Error handling

The SDK exposes SDKHttpError and SDKTimeoutError:

<?php

use NeuronSearchLab\SDKHttpError;
use NeuronSearchLab\SDKTimeoutError;

try {
    $sdk->getRecommendations(['userId' => 'user-123']);
} catch (SDKHttpError $error) {
    error_log(sprintf('HTTP %d: %s', $error->status, $error->statusText));
} catch (SDKTimeoutError $error) {
    error_log(sprintf('Request timed out after %dms', $error->timeoutMs));
}

Transient errors such as 429s, 5xxs, and timeouts are retried automatically.

Logging

Configure structured logging for debugging and observability:

<?php

use function NeuronSearchLab\configureLogger;

configureLogger([
    'level' => 'DEBUG',
    'enableNetworkBodyLogging' => true,
    'enablePerformanceLogging' => true,
]);

Available log levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.

Session management

The SDK auto-generates a session UUID on initialization when autoSessionId is enabled. You can override or read it:

$sdk->setSessionId('custom-session-id');
var_dump($sdk->getSessionId());

JavaScript SDK

MCP Integration

PHP SDK

Installation

Initialize the client

Configuration options

Get recommendations

Search

Searches your own engine runs

Auto-generated sections

Track events

How batching works in PHP

Request ID propagation

Manage catalog items

Create an item

Update an item

Delete items

Error handling

Logging

Session management

Links

​Installation

​Initialize the client

​Configuration options

​Get recommendations

​Search

​Searches your own engine runs

​Auto-generated sections

​Track events

​How batching works in PHP

​Request ID propagation

​Manage catalog items

​Create an item

​Update an item

​Delete items

​Error handling

​Logging

​Session management

​Links

Installation

Initialize the client

Configuration options

Get recommendations

Search

Searches your own engine runs

Auto-generated sections

Track events

How batching works in PHP

Request ID propagation

Manage catalog items

Create an item

Update an item

Delete items

Error handling

Logging

Session management

Links