Znojil Heureka

A simple and modern PHP library for communicating with the Heureka API.

The library covers services for fetching reviews, the category tree, and the Verified by Customers (Ověřeno zákazníky) service.

🌐 Supported Regions

This library supports the following regions:

• Heureka.cz
• Heureka.sk

🔑 Service Activation

To use the Verified by Customers (Ověřeno zákazníky) service, you must first activate it here.

🚀 Installation

Install the library using Composer:

composer require znojil/heureka

📖 Usage

1. Client Initialization

First, you need to create a client instance. The client requires a region (.cz or .sk) and an API key for services that need authentication.

use Znojil\Heureka\Client;
use Znojil\Heureka\Enum\Region;

// For Heureka.cz
$clientCz = new Client(Region::Cz, 'YOUR_API_KEY_FOR_CZ');

// For Heureka.sk
$clientSk = new Client(Region::Sk, 'YOUR_API_KEY_FOR_SK');

2. Using a Custom HTTP Client

You can inject your own HTTP client implementation by passing it as the third argument to the Client constructor. This is useful for testing or for integrating with your application's existing HTTP layer (e.g., Guzzle, Symfony HTTP Client).

Your client must implement the Znojil\Heureka\Http\Client interface.

use Znojil\Heureka\Client;
use Znojil\Heureka\Enum\Region;
use Znojil\Heureka\Http\Client as HeurekaHttpClient;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\UriInterface;

// A custom HTTP client implementation example
class MyCustomHttpClient implements HeurekaHttpClient{
	public function send(string $method, UriInterface|string $uri, array $headers = [], mixed $data = null, array $options = []): ResponseInterface{
		// your implementation
	}
}

$customHttpClient = new MyCustomHttpClient;
$client = new Client(Region::Cz, 'YOUR_API_KEY', $customHttpClient);

Your implementation must honor the Znojil\Heureka\Http\Option::* keys passed in $options (e.g. Option::Timeout — the ShopCertification order log request sets a short timeout) and must reject unknown string keys with an exception. Integer keys are raw CURLOPT_* constants — non-cURL implementations must reject them with an exception rather than silently ignore them, so that a consumer never ends up with options that silently don't apply.

3. Fetching the Category Tree

This service does not require an API key.

use Znojil\Heureka\Feed\Request\GetCategoryTreeRequest;

$request = new GetCategoryTreeRequest;
$categoryTreeCollection = $clientCz->send($request);

foreach($categoryTreeCollection as $tree){
	$tree; // CategoryTreeDTO
}

4. Fetching Shop Reviews

This service requires an API key. The response is an array of ShopReviewDTO objects.

use Znojil\Heureka\Feed\Request\GetShopReviewsRequest;

$request = new GetShopReviewsRequest;
$reviews = $clientCz->send($request);

foreach($reviews as $review){
	$review; // ShopReviewDTO
}

5. Fetching Product Reviews

This service requires an API key. You can optionally set a date from which to fetch the reviews. The response is an array of ProductReviewDTO objects.

use Znojil\Heureka\Feed\Request\GetProductReviewsRequest;

// Without a date filter
$requestAll = new GetProductReviewsRequest;
$allReviews = $clientCz->send($requestAll);

// Only reviews since yesterday
$yesterday = new \DateTimeImmutable('yesterday');
$requestSince = new GetProductReviewsRequest($yesterday);
$recentReviews = $clientCz->send($requestSince);

6. Sending an Order (Verified by Customers)

This service sends order information to the Verified by Customers (Ověřeno zákazníky) system. It requires an API key and uses the new v2 API.

use Znojil\Heureka\ShopCertification\LogOrderDTO;
use Znojil\Heureka\ShopCertification\OrderLogRequest;

// 1. Create a DTO with the order data
$orderDto = new LogOrderDTO(
	email: '[email protected]',
	orderId: 'ORD2024001',
	productItemIds: ['AB-123', 'CD-456']
);

// 2. Create the request and send it
$request = new OrderLogRequest($orderDto);
$response = $clientCz->send($request);

if($response->isSuccessful()){
	echo "Order was successfully logged.";
}

For more details, see the official Heureka 'Verified by Customers' documentation.

⚠️ Error Handling

The client throws exceptions to help you identify the issue:

• Znojil\Heureka\Exception\XmlParseException: When a feed response body cannot be parsed as XML.
• Znojil\Heureka\Exception\JsonException: When the ShopCertification response is not valid JSON.
• Znojil\Heureka\Exception\ClientException: For client-side errors (HTTP 4xx).
• Znojil\Heureka\Exception\ServerException: For server-side errors (HTTP 5xx).
• Znojil\Heureka\Exception\ResponseException: For other HTTP error codes.
• Znojil\Heureka\Exception\LogicException: If you try to call a service that requires an API key without one being set.
• Znojil\Heureka\Exception\InvalidArgumentException: For unknown HTTP client option keys.

use Znojil\Heureka\Exception\ClientException;
use Znojil\Heureka\Exception\ResponseException;
use Znojil\Heureka\Exception\ServerException;

try{
	$response = $client->send(new OrderLogRequest($orderDto));
}catch(ClientException $e){
	// HTTP client error (4xx)
	echo $e->getMessage(); // error details from Heureka
	echo $e->getCode(); // HTTP status code
}catch(ServerException $e){
	// Heureka server error (5xx)
}catch(ResponseException $e){
	// any other unexpected HTTP status
}

All exceptions thrown by the library implement the Znojil\Heureka\Exception\Exception marker interface, so a single catch can cover them all.

📄 License

This library is open-source software licensed under the MIT license.