Luigi's Box Bundle

https://github.com/answear/luigis-box-bundle
Admin
Luigi's Box Bundle is a Symfony integration package that enables developers to integrate Luigi's Box...
Tokens:82,752
Snippets:539
Trust Score:6.8
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Usage example with RecommendationsRequestInterface

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/recommendations-value-objects.md

Shows how to create a RecommendationsCollection with a Recommendation and pass it to the recommendations API via RecommendationsRequestInterface. The example uses named arguments for recommendationType, userId, itemIds, size, hitFields, blacklistedItemIds, and markFallbackResults.

```php
use Answear\LuigisBoxBundle\Service\RecommendationsRequestInterface;
use Answear\LuigisBoxBundle\ValueObject\Recommendation;
use Answear\LuigisBoxBundle\ValueObject\RecommendationsCollection;

/** @var RecommendationsRequestInterface $request */

$collection = new RecommendationsCollection([
    new Recommendation(
        recommendationType: 'recently_viewed',
        userId: 'user-42',
        itemIds: ['product/a', 'product/b'],
        size: 8,
        hitFields: ['url', 'title', 'image', 'price'],
        blacklistedItemIds: ['product/c'],
        markFallbackResults: true,
    ),
]);

$response = $request->getRecommendations($collection);
```

--------------------------------

### Install Luigi's Box Bundle with Composer

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Install the bundle via Composer using the `composer require` command.

```bash
composer require answear/luigis-box-bundle
```

--------------------------------

### Add Dynamic Configuration with ConfigDTO

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Add an additional configuration at runtime using `ConfigProvider::addConfig()` with a `ConfigDTO` instance.

```php
use Answear\LuigisBoxBundle\DTO\ConfigDTO;
use Answear\LuigisBoxBundle\Service\ConfigProvider;

/** @var ConfigProvider $configProvider **/
$configProvider->addConfig('your_config_name', new ConfigDTO(...));
```

--------------------------------

### AbstractContentUpdate::getActiveFrom

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/content-update-value-objects.md

Returns the ISO 8601 availability start.

```APIDOC
## AbstractContentUpdate::getActiveFrom

### Description
Returns the ISO 8601 availability start.

### Method
Getter

### Signature
`getActiveFrom(): ?string`

### Return Value
- **?string** - ISO 8601 availability start, e.g. `2019-05-17T21:12:35+00:00`
```

--------------------------------

### Switch Active Config with ConfigProvider

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Use `ConfigProvider::setConfig()` to switch to a different configuration when multiple configs are defined.

```php
use Answear\LuigisBoxBundle\Service\ConfigProvider;

/** @var ConfigProvider $configProvider **/
$configProvider->setConfig('your_config_name');
```

--------------------------------

### Usage example for ConfigDTO with ConfigProvider

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/util-and-serializer.md

Shows how to add a dynamic configuration for a campaign using ConfigProvider::addConfig() and then set it as active. The searchCacheTtl is set to 60, which is clamped to max 300.

```php
use Answear\LuigisBoxBundle\DTO\ConfigDTO;
use Answear\LuigisBoxBundle\Service\ConfigProvider;

/** @var ConfigProvider $configProvider */
$configProvider->addConfig(
    'campaign',
    new ConfigDTO(
        publicKey: 'pk_campaign',
        privateKey: 'sk_campaign',
        searchCacheTtl: 60,   // clamped to max 300
    )
);
$configProvider->setConfig('campaign');
```

--------------------------------

### Usage example for LuigisBoxSerializer::serialize

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/util-and-serializer.md

Shows how to serialize a ContentRemovalCollection into JSON. The output is a JSON array with url and type fields.

```php
use Answear\LuigisBoxBundle\Service\LuigisBoxSerializer;
use Answear\LuigisBoxBundle\ValueObject\ContentRemovalCollection;

/** @var LuigisBoxSerializer $serializer */
$json = $serializer->serialize(new ContentRemovalCollection([new ContentRemoval('url', 'type')]));
// [{"url":"url","type":"type"}]
```

--------------------------------

### Configure Luigi's Box Bundle (YAML)

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Define required `publicKey` and `privateKey` for each config. `searchCacheTtl` is in seconds (max 300). `host`, `connectionTimeout`, `requestTimeout`, `searchTimeout`, and `searchCacheTtl` have defaults shown. If only one config exists, `default_config` can be omitted.

```yaml
# config/packages/answear_luigis_box.yaml
answear_luigis_box:
    default_config: second_config_name
    configs:
        your_config_name:
            host: 'https://live.luigisbox.com' #default
            publicKey: 'your_public_key'
            privateKey: 'your_private_key'
            connectionTimeout: 4.0 #default
            requestTimeout: 10.0 #default
            searchTimeout: 6.0 #default
            searchCacheTtl: 0 #default
        second_config_name:
            publicKey: 'your_public_key'
            privateKey: 'your_private_key'
```

--------------------------------

### Search with SearchUrlBuilder

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Builds a search URL with query, filters, prefer, and sort parameters. The resulting URL query is like `size=10&page=3&q=nice+top&f%5B0%5D=type%3Aproduct&f%5B1%5D=category%3Atop&f%5B2%5D=brand%3AMedicine&f%5B3%5D=brand%3AAnswear&sort=size%3Aasc&prefer%5B0%5D=brand%3AAnswear`. The response is a `SearchResponse` object.

```php
use Answear\LuigisBoxBundle\ValueObject\SearchUrlBuilder;

// ...

$page = 3;
$urlBuilder = new SearchUrlBuilder($page);
$urlBuilder
    ->setQuery('nice top')
    ->addFilter('type', 'product')
    ->addFilter('category', 'top')
    ->addFilter('brand', 'Medicine')
    ->addFilter('brand', 'Answear')
    ->addPrefer('brand', 'Answear')
    ->setSort('size', 'asc');

//the above code produces a url query like `size=10&page=3&q=nice+top&f%5B0%5D=type%3Aproduct&f%5B1%5D=category%3Atop&f%5B2%5D=brand%3AMedicine&f%5B3%5D=brand%3AAnswear&sort=size%3Aasc&prefer%5B0%5D=brand%3AAnswear`

/** @var \Answear\LuigisBoxBundle\Service\SearchRequestInterface $request **/
$searchResponse = $request->search($urlBuilder);
```

--------------------------------

### RecommendationsRequestInterface

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/types.md

Interface for recommendation requests, marked @experimental. Defines a method to get recommendations.

```APIDOC
## RecommendationsRequestInterface

### Description
Interface for recommendation requests, marked `@experimental`. Defines a method to get recommendations.

### Methods

#### getRecommendations(RecommendationsCollection $recommendationsCollection): ApiResponse
- **Parameters**: `$recommendationsCollection` (RecommendationsCollection) - Required - Collection of recommendation objects.
- **Returns**: ApiResponse

```

--------------------------------

### UpdateByRequestStatusFactory class

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/update-by-query-service.md

Factory that builds the status GET request. The prepareRequest method constructs GET {host}/v1/update_by_query?job_id={$jobId} with signed authorization headers.

```php
class UpdateByRequestStatusFactory
{
    private const ENDPOINT = '/' . ConfigProvider::API_VERSION . '/update_by_query';

    public function __construct(private ConfigProvider $configProvider)
    {}

    public function prepareRequest(int $jobId): Request
}
```

--------------------------------

### Update by query with UpdateByQuery

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Creates an update-by-query request with a search and update specification. The response provides a job ID via `getJobId()`.

```php
use Answear\LuigisBoxBundle\ValueObject\UpdateByQuery;

// ...
$types = ['product'];
$fields = ['color' => 'green'];
$search = new UpdateByQuery\Search($types, $fields);

$updateFields = ['color' => ['olive', 'emerald']];
$update = new UpdateByQuery\Update($updateFields);

$updateByQuery = new UpdateByQuery($search, $update);

/** @var \Answear\LuigisBoxBundle\Service\UpdateByQueryRequest $request **/
$response = $request->update($updateByQuery);

$jobId = $response->getJobId();
```

--------------------------------

### Usage example for update-by-query

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/update-by-query-value-objects.md

Shows how to create Search and Update objects, send an update request, and check job status. The jobId comes from the response and is passed to getStatus().

```php
use Answear\LuigisBoxBundle\Service\UpdateByQueryRequestInterface;
use Answear\LuigisBoxBundle\ValueObject\UpdateByQuery;

/** @var UpdateByQueryRequestInterface $request */

$search = new UpdateByQuery\Search(['product'], ['color' => 'green']);
$update = new UpdateByQuery\Update(['color' => ['olive', 'emerald']]);

$response = $request->update(new UpdateByQuery($search, $update));
$jobId = $response->getJobId();

$status = $request->getStatus($jobId);
if ($status->isCompleted()) {
    echo $status->okCount;
}
```

--------------------------------

### Catch request exceptions

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Shows how to catch Luigi's Box request exceptions separately. BadRequestException, TooManyItemsException, MalformedResponseException, TooManyRequestsException, and ServiceUnavailableException are available.

```php

use Answear\LuigisBoxBundle\Exception\BadRequestException;
use Answear\LuigisBoxBundle\Exception\TooManyItemsException;
use Answear\LuigisBoxBundle\Exception\MalformedResponseException;
use Answear\LuigisBoxBundle\Exception\TooManyRequestsException;
use Answear\LuigisBoxBundle\Exception\ServiceUnavailableException;

try {
    // ... request
} catch (BadRequestException $exception){
    //bad request
    $request = $exception->request;
    $response = $exception->response;
} catch (TooManyItemsException $exception){
    //items limit reached
    $limit = $exception->limit;
} catch (MalformedResponseException $exception){
    //bad response
    $response = $exception->response;
} catch (TooManyRequestsException $exception){
    //repeat request after $retryAfter seconds
    $retryAfter = $exception->retryAfterSeconds;
} catch (ServiceUnavailableException $exception){
    //delay request
}
```

--------------------------------

### AbstractContentUpdate::setActiveFrom

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/content-update-value-objects.md

Sets the ISO 8601 availability start.

```APIDOC
## AbstractContentUpdate::setActiveFrom

### Description
Sets the ISO 8601 availability start.

### Method
Setter

### Signature
`setActiveFrom(?string $activeFrom): void`

### Parameters
- **$activeFrom** (?string) - Required - ISO 8601 availability start
```

--------------------------------

### SearchResponse usage example

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/response-objects.md

Shows how to access totalHits, currentSize, and iterate facets and their values after obtaining a SearchResponse instance.

```php
/** @var \Answear\LuigisBoxBundle\Response\SearchResponse $response */
echo $response->totalHits;
echo $response->currentSize;

foreach ($response->facets as $facet) {
    echo $facet->name . ' (' . $facet->type . ')';
    foreach ($facet->values as $value) {
        echo $value->value . ': ' . $value->hitsCount;
    }
}
```

--------------------------------

### Change availability with ContentAvailabilityCollection

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Enables or disables objects using a partial update. Accepts a collection or a single ContentAvailability object.

```php
use Answear\LuigisBoxBundle\ValueObject\ContentAvailability;
use Answear\LuigisBoxBundle\ValueObject\ContentAvailabilityCollection;

// ...

$isAvailable = true;
$collection = new ContentAvailabilityCollection([new ContentAvailability('product/url', $isAvailable)]);

/** @var \Answear\LuigisBoxBundle\Service\RequestInterface $request **/
$apiResponse = $request->changeAvailability($collection);

// ... or pass one object

$isAvailable = true;
/** @var \Answear\LuigisBoxBundle\Service\RequestInterface $request **/
$apiResponse = $request->changeAvailability(new ContentAvailability('product/url', $isAvailable));
```

--------------------------------

### Usage of AuthenticationUtil

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/util-and-serializer.md

Demonstrates how to call getRequestHeaders and digest with example keys and a DateTimeImmutable instance. The getRequestHeaders call returns an array with Content-Type, date, and Authorization headers.

```php
use Answear\LuigisBoxBundle\Util\AuthenticationUtil;

$headers = AuthenticationUtil::getRequestHeaders(
    'public-key',
    'private-key',
    'POST',
    '/v1/content',
    new \DateTimeImmutable(),
);

$digest = AuthenticationUtil::digest('private-key', 'GET', '/v1/content', new \DateTimeImmutable());
```

--------------------------------

### Partial content update with PartialContentUpdate

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Sends a partial content update to Luigi's Box, updating only specified fields for an existing object.

```php
use Answear\LuigisBoxBundle\ValueObject\ContentUpdateCollection;
use Answear\LuigisBoxBundle\ValueObject\PartialContentUpdate;

// ...

$collection = new ContentUpdateCollection([new PartialContentUpdate('product/url', 'object type', ['title' => 'product title'])]);

/** @var \Answear\LuigisBoxBundle\Service\RequestInterface $request **/
$apiResponse = $request->partialContentUpdate($collection);
```

--------------------------------

### UpdateByQueryRequest class constructor

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/update-by-query-service.md

Implements the interface with dependencies: a Guzzle client, a factory for the PATCH request, and a factory for the status GET request. All are required.

```php
class UpdateByQueryRequest implements UpdateByQueryRequestInterface
{
    public function __construct(
        private Client $client,
        private UpdateByRequestFactory $factory,
        private UpdateByRequestStatusFactory $statusFactory,
    )
    {}
}
```

--------------------------------

### Enable/disable documents usage example

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/content-removal-value-objects.md

Shows two variants of calling Request::changeAvailability(): with a single ContentAvailability and with a ContentAvailabilityCollection for batch. The batch variant uses true to enable and false to disable.

```php
use Answear\LuigisBoxBundle\Service\RequestInterface;
use Answear\LuigisBoxBundle\ValueObject\ContentAvailability;
use Answear\LuigisBoxBundle\ValueObject\ContentAvailabilityCollection;

/** @var RequestInterface $request */

$response = $request->changeAvailability(new ContentAvailability('product/url', true));

// batch variant:
$response = $request->changeAvailability(new ContentAvailabilityCollection([
    new ContentAvailability('product/url', true),
    new ContentAvailability('product/other-url', false),
]));
```

--------------------------------

### UpdateByQueryRequest::getStatus()

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Retrieves the status of an update-by-query job using its job ID. Returns an UpdateByQueryStatusResponse with completion status and error details.

```APIDOC
## UpdateByQueryRequest::getStatus()

### Description
Retrieves the status of an update-by-query job using its job ID. Returns an UpdateByQueryStatusResponse with completion status and error details.

### Method
getStatus

### Parameters
- **jobId** (int) - Required - The job ID returned from the update request.

### Request Example
```php
$jobId = 1;
$response = $request->getStatus($jobId);
```

### Response
#### UpdateByQueryStatusResponse
- **rawResponse** (array) - Raw response data.
- **trackerId** (string) - Tracker ID.
- **completed** (bool) - Whether the job is completed.
- **okCount** (int|null) - Number of successful updates, null if not completed.
- **errorsCount** (int|null) - Number of errors, null if not completed.
- **errors** (ApiResponseError[]|null) - List of errors, null if not completed.

### Response Example
```json
{
  "rawResponse": {},
  "trackerId": "tracker123",
  "completed": true,
  "okCount": 10,
  "errorsCount": 0,
  "errors": null
}
```
```

--------------------------------

### Set and Reset Custom Headers for Search Requests

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Pass custom headers to search requests using `ConfigProvider::setHeader()`. Call `resetHeaders()` to clear all custom headers.

```php
use Answear\LuigisBoxBundle\Service\ConfigProvider;

/** @var ConfigProvider $configProvider **/
$configProvider->setHeader('header-name', 'header-value');

/* reset all headers */
$configProvider->resetHeaders();
```

--------------------------------

### SearchRequest::search()

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Performs a search request using the Luigi's Box Search API. Builds a search URL with SearchUrlBuilder and returns a SearchResponse object containing search results, facets, and hits.

```APIDOC
## SearchRequest::search()

### Description
Performs a search request using the Luigi's Box Search API. Builds a search URL with SearchUrlBuilder and returns a SearchResponse object containing search results, facets, and hits.

### Method
search

### Parameters
#### SearchUrlBuilder
- **page** (int) - Required - Page number for pagination.
- **query** (string) - Optional - Search query string.
- **filters** (array) - Optional - Key-value pairs where key is filter name and value is filter value. Multiple values for same key are allowed.
- **prefer** (array) - Optional - Key-value pairs for preferred values.
- **sort** (string) - Optional - Sort field and direction in format 'field:direction'.
- **bodyFilterGroups** (array) - Optional - Nested filter groups for complex boolean logic. Each group is an array with 'type' and 'conditions'.

### Request Example
```php
$urlBuilder = new SearchUrlBuilder(3);
$urlBuilder
    ->setQuery('nice top')
    ->addFilter('type', 'product')
    ->addFilter('category', 'top')
    ->addFilter('brand', 'Medicine')
    ->addFilter('brand', 'Answear')
    ->addPrefer('brand', 'Answear')
    ->setSort('size', 'asc');
$searchResponse = $request->search($urlBuilder);
```

### Response
#### SearchResponse
- **searchUrl** (string) - The search URL used.
- **query** (string) - The search query.
- **correctedQuery** (string|null) - Corrected query if any.
- **filters** (array) - Applied filters.
- **hits** (Hit[]) - List of hits.
- **quickSearchHits** (Hit[]) - List of quick search hits.
- **facets** (Facet[]) - List of facets.
- **totalHits** (int) - Total number of hits.
- **currentSize** (int) - Current page size.

#### Hit
- **url** (string) - URL of the hit.
- **attributes** (array) - Attributes of the hit.
- **nested** (array) - Nested data.
- **type** (string) - Type of the hit.
- **highlight** (array) - Highlighted fields.
- **exact** (bool) - Whether the hit is exact.
- **alternative** (bool) - Whether the hit is an alternative.

#### Facet
- **name** (string) - Facet name.
- **type** (string) - Facet type.
- **values** (array) - Facet values.

### Response Example
```json
{
  "searchUrl": "...",
  "query": "nice top",
  "correctedQuery": null,
  "filters": [],
  "hits": [],
  "quickSearchHits": [],
  "facets": [],
  "totalHits": 0,
  "currentSize": 10
}
```
```

--------------------------------

### UpdateByQueryRequest::update()

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Sends an update-by-query request to Luigi's Box to update documents matching a search query. Returns a response containing a job ID for tracking the update.

```APIDOC
## UpdateByQueryRequest::update()

### Description
Sends an update-by-query request to Luigi's Box to update documents matching a search query. Returns a response containing a job ID for tracking the update.

### Method
update

### Parameters
#### UpdateByQuery
- **search** (Search) - Required - Search criteria for selecting documents to update.
  - **types** (string[]) - Required - Document types to update.
  - **fields** (array) - Required - Field-value pairs to match.
- **update** (Update) - Required - Fields to update.
  - **fields** (array) - Required - Field-value pairs to set.

### Request Example
```php
$search = new UpdateByQuery\Search(['product'], ['color' => 'green']);
$update = new UpdateByQuery\Update(['color' => ['olive', 'emerald']]);
$updateByQuery = new UpdateByQuery($search, $update);
$response = $request->update($updateByQuery);
$jobId = $response->getJobId();
```

### Response
#### UpdateByQueryResponse
- **jobId** (string) - The job ID for tracking the update.

### Response Example
```json
{
  "jobId": "12345"
}
```
```

--------------------------------

### Retrieve job status with getStatus

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Fetches the status of an update-by-query job using its job ID. Returns an `UpdateByQueryStatusResponse` with fields like `trackerId`, `completed`, `okCount`, `errorsCount`, and `errors`.

```php
use Answear\LuigisBoxBundle\ValueObject\UpdateByQuery;

$jobId = 1;

/** @var \Answear\LuigisBoxBundle\Service\UpdateByQueryRequest $request **/
$response = $request->getStatus($jobId);
```

--------------------------------

### Submit a job and poll until completion

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/update-by-query-service.md

Creates an UpdateByQuery with a search filter and field updates, then submits it via update() to get a job ID. The search matches products where color is green; the update sets color to olive or emerald.

```php
use Answear\LuigisBoxBundle\Service\UpdateByQueryRequest;
use Answear\LuigisBoxBundle\ValueObject\UpdateByQuery;

/** @var UpdateByQueryRequest $request */

$search = new UpdateByQuery\Search(['product'], ['color' => 'green']);
$update = new UpdateByQuery\Update(['color' => ['olive', 'emerald']]);
$updateByQuery = new UpdateByQuery($search, $update);

$response = $request->update($updateByQuery);
$jobId = $response->getJobId();
```

--------------------------------

### Content removal usage example

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/content-removal-value-objects.md

Creates a ContentRemovalCollection with two ContentRemoval objects and calls Request::contentRemoval(). Sends DELETE /v1/content with body [{"url":"product/url","type":"product"}, ...].

```php
use Answear\LuigisBoxBundle\Service\RequestInterface;
use Answear\LuigisBoxBundle\ValueObject\ContentRemoval;
use Answear\LuigisBoxBundle\ValueObject\ContentRemovalCollection;

/** @var RequestInterface $request */

$collection = new ContentRemovalCollection([
    new ContentRemoval('product/url', 'product'),
    new ContentRemoval('product/other-url', 'product'),
]);

$response = $request->contentRemoval($collection);
// DELETE /v1/content with body [{"url":"product/url","type":"product"}, ...]
```

--------------------------------

### Full content update with ContentUpdateCollection

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Sends a full content update to Luigi's Box. The first argument ($title) is used as the product title unless a 'title' field is present in the $fields argument.

```php
use Answear\LuigisBoxBundle\ValueObject\ContentUpdate;
use Answear\LuigisBoxBundle\ValueObject\ContentUpdateCollection;

// ...

$collection = new ContentUpdateCollection([new ContentUpdate('product title', 'product/url', 'object type', ['field' => 'field 1'])]);

/** @var \Answear\LuigisBoxBundle\Service\RequestInterface $request **/
$apiResponse = $request->contentUpdate($collection);
```

--------------------------------

### RecommendationsFactory class with prepareRequest

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/recommendations-service.md

Factory that builds the POST /v1/recommend request. prepareRequest overrides the parent to construct the URI with tracker_id query param. Headers come from ConfigProvider::getAuthorizationHeaders and body from LuigisBoxSerializer::serialize.

```php
class RecommendationsFactory extends AbstractFactory
{
    private const HTTP_METHOD = 'POST';
    private const ENDPOINT = '/' . ConfigProvider::API_VERSION . '/recommend';

    public function __construct(
        private ConfigProvider $configProvider,
        private LuigisBoxSerializer $serializer,
    )
    {}

    public function prepareRequest(ObjectsInterface $bodyObject): Request
}
```

--------------------------------

### GET /search

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/endpoints.md

Performs a search query against Luigi's Box. Supports GET with query parameters or POST with a JSON body containing filters. Returns search results including hits, facets, and query corrections.

```APIDOC
## [GET] /search

### Description
Performs a search query against Luigi's Box. Supports GET with query parameters or POST with a JSON body containing filters. Returns search results including hits, facets, and query corrections.

### Method
GET (default) or POST (when body filter groups are set)

### Endpoint
`/search?tracker_id={publicKey}&{urlQuery}`

### Parameters
#### Query Parameters
- **size** (int) - Optional - Page size (default 10)
- **page** (int) - Optional - Page number (constructor arg, default 1)
- **q** (string) - Optional - Query text
- **qu** (0|1) - Optional - Query understanding (requires `user_id`)
- **user_id** (string) - Optional - User id
- **client_id** (string) - Optional - Client id
- **f** (string[]) - Optional - Filters, each `key:value`
- **f_must** (string[]) - Optional - Must-filters, each `key:value`
- **sort** (string) - Optional - `field:asc|desc`
- **quicksearch_types** (string) - Optional - Comma-joined types
- **facets** (string) - Optional - Comma-joined facet fields
- **dynamic_facets_size** (int) - Optional - Dynamic facet size
- **use_fixits** (0|1) - Optional - Fixits toggle
- **prefer** (string[]) - Optional - Preferred values, each `key:value`
- **hit_fields** (string) - Optional - Comma-joined hit fields
- **context** (object) - Optional - `{geo_location, geo_location_field, availability_field, boost_field, freshness_field}` (populated only for non-null `Search\Context` values)

#### Request Body (POST only)
- **filters** (object) - Required - Filter groups

### Request Example
```json
{
  "filters": {}
}
```

### Response
#### Success Response (200)
- **guid** (string) - Top-level response identifier
- **results** (object) - Contains:
  - **query** (string) - The query text
  - **corrected_query** (string) - Corrected query if any
  - **filters** (array) - List of `key:value` filter strings
  - **hits** (array) - Each hit: `url`, `attributes`, `nested`, `type`, `highlight`, `exact`, `alternative`
  - **quicksearch_hits** (array) - Each hit: `url`, `attributes`, `nested`, `type`, `highlight`, `exact`, `alternative`
  - **facets** (array) - Each facet: `name`, `type`, `values[{value, hits_count}]`
  - **total_hits** (int) - Total number of hits
  - **offset** (int) - Offset for pagination

#### Response Example
```json
{
  "guid": "...",
  "results": {
    "query": "...",
    "corrected_query": "...",
    "filters": ["key:value"],
    "hits": [
      {
        "url": "...",
        "attributes": {},
        "nested": {},
        "type": "...",
        "highlight": {},
        "exact": true,
        "alternative": false
      }
    ],
    "quicksearch_hits": [],
    "facets": [
      {
        "name": "...",
        "type": "...",
        "values": [
          {
            "value": "...",
            "hits_count": 0
          }
        ]
      }
    ],
    "total_hits": 0,
    "offset": 0
  }
}
```

### Error Handling
- **404** or **400** → `BadRequestException`
- **429** or **413** or transport errors → handled by `AbstractClient`
```

--------------------------------

### RecommendationsRequest class constructor

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/recommendations-service.md

Implementation of RecommendationsRequestInterface. Constructor injects RecommendationsFactory and RecommendationsClient. The factory builds the POST /v1/recommend request with tracker_id query param; the client uses dedicated recommendations timeouts.

```php
class RecommendationsRequest implements RecommendationsRequestInterface
{
    public function __construct(
        private RecommendationsFactory $recommendationsFactory,
        private RecommendationsClient $recommendationsClient,
    )
    {}
}
```

--------------------------------

### RecommendationsRequestInterface with getRecommendations method

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/recommendations-service.md

Defines the experimental interface for sending recommendation requests. The method getRecommendations accepts a RecommendationsCollection and returns an ApiResponse. Marked @experimental, breaking changes may occur.

```php
interface RecommendationsRequestInterface
{
    /**
     * @experimental This feature is in an experimental stage. Breaking changes may occur without prior notice.
     */
    public function getRecommendations(RecommendationsCollection $recommendationsCollection): ApiResponse;
}
```

--------------------------------

### UpdateByQueryRequestInterface

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/types.md

Interface for update-by-query requests. Defines methods to update by query and get job status.

```APIDOC
## UpdateByQueryRequestInterface

### Description
Interface for update-by-query requests. Defines methods to update by query and get job status.

### Methods

#### update(UpdateByQuery $updateByQuery): UpdateByQueryResponse
- **Parameters**: `$updateByQuery` (UpdateByQuery) - Required - The update-by-query object.
- **Returns**: UpdateByQueryResponse

#### getStatus(int $jobId): UpdateByQueryStatusResponse
- **Parameters**: `$jobId` (int) - Required - The job ID.
- **Returns**: UpdateByQueryStatusResponse

```

--------------------------------

### Content removal with ContentRemovalCollection

Source: https://github.com/answear/luigis-box-bundle/blob/master/README.md

Removes content from Luigi's Box by specifying the object URL and type.

```php
use Answear\LuigisBoxBundle\ValueObject\ContentRemoval;
use Answear\LuigisBoxBundle\ValueObject\ContentRemovalCollection;

// ...

$collection = new ContentRemovalCollection([new ContentRemoval('product/url', 'product')]);

/** @var \Answear\LuigisBoxBundle\Service\RequestInterface $request **/
$apiResponse = $request->contentRemoval($collection);
```

--------------------------------

### AbstractClient::__construct

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/http-clients.md

Initializes the client with a config provider and optional custom Guzzle client. If no custom client is provided, the abstract getGuzzleClient() method is used.

```APIDOC
## [POST] AbstractClient::__construct

### Description
Initializes the client with a config provider and optional custom Guzzle client. If no custom client is provided, the abstract getGuzzleClient() method is used.

### Method
POST

### Endpoint
AbstractClient::__construct

### Parameters
#### Path Parameters
- **$configProvider** (ConfigProvider) - Required - Source of timeouts
- **$client** (\GuzzleHttp\Client) - Optional - Custom Guzzle client; when null, getGuzzleClient() is used

### Response
#### Success Response (200)
- **void** - No return value
```

--------------------------------

### setFilters

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/search-value-objects.md

Replaces all filters at once. Throws a LogicException if filters already exist, and asserts all keys are strings.

```APIDOC
## setFilters

### Description
Replaces all filters at once. Throws a `\LogicException` if filters already exist, and asserts all keys are strings.

### Method
setFilters

### Signature
`setFilters(array $filters): self`

### Parameters
- **$filters** (array) - Required - An associative array of filters, where keys are strings and values are bool|int|string.

### Exceptions
- **\LogicException** - Thrown if filters already exist. Message: `You already have the filters set. Use resetFilters() method to clear them first.`

### Return Value
- **self** - Returns the current instance for chaining.
```

--------------------------------

### Inspecting recommendation failures

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/recommendations-service.md

Wraps getRecommendations in a try-catch. On success, iterates response errors to print per-recommendation failure reasons. Catches ServiceUnavailableException for transport-level failures, suggesting retry later.

```php
use Answear\LuigisBoxBundle\Exception\ServiceUnavailableException;
use Answear\LuigisBoxBundle\Service\RecommendationsRequestInterface;
use Answear\LuigisBoxBundle\ValueObject\RecommendationsCollection;

/** @var RecommendationsRequestInterface $request */

try {
    $response = $request->getRecommendations($collection);
    foreach ($response->errors as $error) {
        echo $error->reason; // per-recommendation failure detail
    }
} catch (ServiceUnavailableException $e) {
    // transport-level failure; consider retrying later
}
```

--------------------------------

### Request construction outline

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/content-factories.md

Shows the structure of the built request: HTTP method, host, endpoint, headers from ConfigProvider, and serialized body. The date header uses \DateTime::createFromFormat('U', (string) time()).

```text
{HTTP method} {host}{endpoint}
Headers: ConfigProvider::getAuthorizationHeaders(method, endpoint, now)  // Content-Type, date, Authorization
Body:    LuigisBoxSerializer::serialize($bodyObject)                      // JSON
```

--------------------------------

### Switching configurations and adding custom search headers

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/config-provider.md

Shows how to switch between YAML-declared configs, add a runtime config via ConfigDTO, and set or reset custom headers for search requests. The setHeader method forwards headers only on search requests, and resetHeaders clears them.

```php
use Answear\LuigisBoxBundle\DTO\ConfigDTO;
use Answear\LuigisBoxBundle\Service\ConfigProvider;

/** @var ConfigProvider $configProvider */

// Switch to a config declared in YAML.
$configProvider->setConfig('second_config_name');

// Add a runtime config.
$configProvider->addConfig('emergent', new ConfigDTO(
    publicKey: 'pk_live_x',
    privateKey: 'sk_live_y',
    host: 'https://live.luigisbox.com',
));

// Custom headers forwarded on search requests only.
$configProvider->setHeader('x-custom', 'value');
$configProvider->resetHeaders();
```

--------------------------------

### POST /v1/recommend

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/endpoints.md

Fetches recommendations (experimental). Used by RecommendationsRequest::getRecommendations().

```APIDOC
## [POST] /v1/recommend

### Description
Fetches recommendations (experimental). Used by RecommendationsRequest::getRecommendations().

### Method
POST

### Endpoint
/v1/recommend?tracker_id={publicKey}

### Parameters
#### Query Parameters
- **tracker_id** (string) - Required - Public key for tracker identification.

#### Request Body
- **Recommendation[]** (array) - Required - Unwrapped array from RecommendationsCollection; nullable fields skipped.

### Response
#### Success Response (200)
- **ApiResponse** - With `allCount = 0`, so `success` only when `ok_count === 0`.

#### Response Example
{
  "example": "ApiResponse shape"
}
```

--------------------------------

### Error handling for setConfig and setHeader

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/config-provider.md

Demonstrates exceptions thrown by ConfigProvider methods. setConfig with a missing key throws Webmozart\Assert\InvalidArgumentException with a message listing available configurations. setHeader with a reserved header name like 'Authorization' throws BadMethodCallException.

```php
use Answear\LuigisBoxBundle\Service\ConfigProvider;

try {
    $configProvider->setConfig('does-not-exist');
} catch (\Webmozart\Assert\InvalidArgumentException $e) {
    // "No configuration with key "does-not-exist". Available configurations: default."
}

try {
    $configProvider->setHeader('Authorization', 'x'); // reserved
} catch (\BadMethodCallException $e) {
    // "Reserved header name provided: Authorization"
}
```

--------------------------------

### Bundle configuration before 2.0.0

Source: https://github.com/answear/luigis-box-bundle/blob/master/CHANGELOG.md

Configuration format used before version 2.0.0, with publicKey and privateKey at the top level.

```php
answear_luigis_box:
  publicKey: 'public'
  privateKey: 'private'
```

--------------------------------

### Building a raw signed request without the service layer

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/content-factories.md

Shows how to manually create a ContentUpdateFactory and prepare a request. Outputs the HTTP method, URI, Authorization header, and JSON body.

```php
use Answear\LuigisBoxBundle\Factory\ContentUpdateFactory;
use Answear\LuigisBoxBundle\ValueObject\ContentUpdate;
use Answear\LuigisBoxBundle\ValueObject\ContentUpdateCollection;

/** @var ContentUpdateFactory $factory */

$collection = new ContentUpdateCollection([
    new ContentUpdate('title', 'url', 'type', ['field' => 'value']),
]);

$request = $factory->prepareRequest($collection);
echo $request->getMethod();   // "POST"
echo (string) $request->getUri(); // "https://...:/v1/content"
echo $request->getHeaderLine('Authorization'); // "guzzle {publicKey}:{digest}"
echo $request->getBody()->getContents();       // JSON payload
```

--------------------------------

### addPrefer

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/search-value-objects.md

Appends a prefer entry with key:value format; repeated keys accumulate.

```APIDOC
## addPrefer

### Description
Appends a `prefer` entry with `key:value` format; repeated keys accumulate.

### Method
`addPrefer`

### Signature
`addPrefer(string $key, string $value): self`

### Parameters
- **$key** (string) - Required - The key for the prefer entry.
- **$value** (string) - Required - The value for the prefer entry.

### Returns
`self` - Returns the instance for method chaining.
```

--------------------------------

### getStatus(int $jobId): UpdateByQueryStatusResponse

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/update-by-query-service.md

Polls the status of a previously submitted update-by-query job via GET /v1/update_by_query?job_id={id}. Returns a response indicating whether the job is complete and, if so, the counts and errors.

```APIDOC
## [GET] /v1/update_by_query?job_id={id}

### Description
Polls the status of a previously submitted update-by-query job. Returns a response indicating whether the job is complete and, if so, the counts and errors.

### Method
GET

### Endpoint
/v1/update_by_query?job_id={id}

### Parameters
#### Query Parameters
- **job_id** (int) - Required - The job ID returned by `update()`

### Request Example
```php
$status = $request->getStatus($jobId);
```

### Response
#### Success Response (200)
- **completed** (bool) - `true` when the response `status` equals `complete`
- **okCount** (int|null) - Number of successful updates; `null` unless completed
- **errorsCount** (int|null) - Number of failed updates; `null` unless completed
- **errors** (array|null) - List of errors, each with `url` and `reason`; `null` unless completed

#### Response Example
```php
if ($status->isCompleted()) {
    echo $status->okCount . ' ok, ' . $status->errorsCount . ' failed';
    foreach ($status->errors ?? [] as $error) {
        echo $error->url . ': ' . $error->reason;
    }
}
```

### Error Handling
- **BadRequestException** - Status 400 or 404
- **TooManyRequestsException** - Status 429
- **TooManyItemsException** - Status 413
- **ServiceUnavailableException** - Transport error
- **MalformedResponseException** - Empty body or non-array JSON
```

--------------------------------

### ConfigDTO::__construct

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/util-and-serializer.md

Creates a configuration DTO for Luigi's Box API. All parameters have defaults except publicKey and privateKey.

```APIDOC
## ConfigDTO::__construct

### Description
Creates a configuration DTO for Luigi's Box API. All parameters have defaults except publicKey and privateKey.

### Method
__construct

### Parameters
#### Parameters
- **$publicKey** (string) - Required - Luigi's Box public key
- **$privateKey** (string) - Required - Luigi's Box private key
- **$host** (string) - Optional - API host (default: `https://live.luigisbox.com`)
- **$connectionTimeout** (float) - Optional - Connection timeout seconds (default: `4.0`)
- **$requestTimeout** (float) - Optional - Request timeout seconds (content/update-by-query) (default: `10.0`)
- **$searchTimeout** (float) - Optional - Search request timeout seconds (default: `6.0`)
- **$searchCacheTtl** (int) - Optional - Search cache TTL; clamped to `min($searchCacheTtl, 300)`; must be `>= 0` (default: `0`)
- **$recommendationsRequestTimeout** (float) - Optional - Recommendations request timeout seconds (default: `1.0`)
- **$recommendationsConnectionTimeout** (float) - Optional - Recommendations connection timeout seconds (default: `1.0`)

### Usage example
```php
use Answear\LuigisBoxBundle\DTO\ConfigDTO;
use Answear\LuigisBoxBundle\Service\ConfigProvider;

/** @var ConfigProvider $configProvider */
$configProvider->addConfig(
    'campaign',
    new ConfigDTO(
        publicKey: 'pk_campaign',
        privateKey: 'sk_campaign',
        searchCacheTtl: 60,   // clamped to max 300
    )
);
$configProvider->setConfig('campaign');
```
```

--------------------------------

### UpdateByQueryRequest::getStatus method signature

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/update-by-query-service.md

Public method that accepts a job ID and returns an UpdateByQueryStatusResponse. Sends GET /v1/update_by_query?job_id={$jobId}. The response's completed flag is true only when status equals 'complete'.

```php
public function getStatus(int $jobId): UpdateByQueryStatusResponse
```

--------------------------------

### Basic recommendation request usage

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/recommendations-service.md

Creates a RecommendationsCollection with a single Recommendation of type 'also_bought' for user 'user-123', requesting 5 hits with specified fields. Then calls getRecommendations on the request service.

```php
use Answear\LuigisBoxBundle\Service\RecommendationsRequestInterface;
use Answear\LuigisBoxBundle\ValueObject\Recommendation;
use Answear\LuigisBoxBundle\ValueObject\RecommendationsCollection;

/** @var RecommendationsRequestInterface $request */

$collection = new RecommendationsCollection([
    new Recommendation(
        recommendationType: 'also_bought',
        userId: 'user-123',
        size: 5,
        hitFields: ['url', 'title', 'image'],
    ),
]);

$response = $request->getRecommendations($collection);
```

--------------------------------

### Full-featured URL builder with SearchUrlBuilder and Context

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/search-value-objects.md

Builds a search URL with pagination, query, filters, preferences, sorting, and geo/availability/boost/freshness context. Requires the SearchUrlBuilder and Context classes from the LuigisBox bundle.

```php
use Answear\LuigisBoxBundle\ValueObject\Search\Context;
use Answear\LuigisBoxBundle\ValueObject\SearchUrlBuilder;

$context = (new Context())
    ->setGeoLocation(50.0617, 19.9368)
    ->setGeoLocationField('geo')
    ->setAvailabilityField('available')
    ->setBoostField('boost')
    ->setFreshnessField('release_date');

$urlBuilder = (new SearchUrlBuilder(page: 3))
    ->setQuery('nice top')
    ->addFilter('type', 'product')
    ->addFilter('brand', 'Answear')
    ->addPrefer('brand', 'Answear')
    ->setSort('size', 'asc')
    ->setContext($context);

$query = $urlBuilder->toUrlQuery();
```

--------------------------------

### ApiResponse usage example

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/response-objects.md

Checks the response status and iterates over errors, printing each error's URL, type, and reason. Uses the readonly properties okCount, errorsCount, and errors.

```php
use Answear\LuigisBoxBundle\Response\ApiResponse;

/** @var ApiResponse $response */
if ($response->isSuccess()) {
    $processed = $response->okCount;
} else {
    $failed = $response->errorsCount;
    foreach ($response->errors as $error) {
        echo $error->url . ' [' . $error->type . '] ' . $error->reason;
    }
}

```

--------------------------------

### setSize

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/search-value-objects.md

Sets the size parameter for the search query, initialized to DEFAULT_SIZE (10).

```APIDOC
## setSize

### Description
Sets the `size` parameter for the search query, initialized to `DEFAULT_SIZE` (10).

### Method
`setSize`

### Signature
`setSize(int $size): self`

### Parameters
- **$size** (int) - Required - The size value to set.

### Returns
`self` - Returns the instance for method chaining.
```

--------------------------------

### __toString method signature

Source: https://github.com/answear/luigis-box-bundle/blob/master/_autodocs/api-reference/search-value-objects.md

Magic method that returns the result of toUrlQuery().

```php
public function __toString(): string
```
Tokens:
Raw