cultuurnet/search-v3

Cultuurnet search service for version 3

2.0.0 2024-08-08 07:21 UTC

Requires

• php: ^8
• guzzlehttp/guzzle: ^6.5.8|^7.4.5
• jms/serializer: 3.24.0
• simple-bus/jms-serializer-bridge: ^6.3.1

Requires (Dev)

• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^10.4.1
• publiq/php-cs-fixer-config: ^2.0

Apache-2.0

• publiq vzw

README

This PHP library allows you to integrate with publiq's Search API3.

For legacy purposes, we also maintain a separate branch main-php7, if you need compatibility with PHP 7.4.

Full API documentation: https://docs.publiq.be/docs/uitdatabank/search-api/introduction
Getting an API key: https://platform.publiq.be

Installation

composer require cultuurnet/search-v3

Usage

Set up a Guzzle client with a URL and API key for the test environment of Search API3 like this:

$httpClient = new GuzzleHttp\Client([
    'base_uri' => 'https://search-test.uitdatabank.be/',
    'headers' => [
        'X-Api-Key' => 'YOUR_API_KEY_FOR_TEST_ENV',
    ],
]);

Then, set up the search-v3 SearchClient like this:

$searchClient = new CultuurNet\SearchV3\SearchClient(
    $httpClient, // HTTP client set up in the previous step
    new CultuurNet\SearchV3\Serializer\Serializer() // Built-in serializer to deserialize the JSON responses
);

You can then perform searches like this:

$searchQuery = new \CultuurNet\SearchV3\SearchQuery();
$events = $searchClient->searchEvents($searchQuery); // Search events
$places = $searchClient->searchPlaces($searchQuery); // Search places
$offers = $searchClient->searchOffers($searchQuery); // Search both events + places

The results are an instance of \CultuurNet\SearchV3\ValueObjects\PagedCollection, which supports the following methods:

// Get pagination info
$events->getItemsPerPage();
$events->getTotalItems();

// Get the search results, as instances of CultuurNet\SearchV3\ValueObjects\Event
// and CultuurNet\SearchV3\ValueObjects\Place
$events->getMember()->getItems();

// Get the facet results as an instance of CultuurNet\SearchV3\ValueObjects\FacetResults
$events->getFacets();

To customize your search, you can configure \CultuurNet\SearchV3\SearchQuery like this:

$searchQuery = new \CultuurNet\SearchV3\SearchQuery();

// Embed the JSON-LD of the search results, instead of only the ID and type.
$searchQuery->setEmbed(true);

// Set the number of which result to fetch first. Defaults to 0.
// If the first page had a limit of 30 for example, and you want to get the results of the second page, set the start to
// 30. (So the start is always the limit multiplied by the page number you want to get, starting with 0.)
$searchQuery->setStart(0);

// Set the max amount of results to return per page.
$searchQuery->setLimit(30);

// Add a sort (see SAPI3 docs for possible fields to sort on)
$searchQuery->addSort('created', 'ASC');

// Remove a sort
$searchQuery->removeSort('created');

// Add a search parameter (see src/Parameter for all options)
$searchQuery->addParameter(
    new CultuurNet\SearchV3\Parameter\AudienceType(
        CultuurNet\SearchV3\Parameter\AudienceType::AUDIENCE_EDUCATION
    )
);

// Remove a search parameter (see src/Parameter for all options)
$searchQuery->removeParameter(
    new CultuurNet\SearchV3\Parameter\AudienceType(
        CultuurNet\SearchV3\Parameter\AudienceType::AUDIENCE_EDUCATION
    )
);

Some parameters allow multiple options and can be added more than once:

$searchQuery->addParameter(new CultuurNet\SearchV3\Parameter\Label('foo'));
$searchQuery->addParameter(new CultuurNet\SearchV3\Parameter\Label('bar'));
// Will return only results that have both labels.