PHPackages                             znojil/heureka - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. znojil/heureka

ActiveLibrary[API Development](/categories/api)

znojil/heureka
==============

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

v1.1.2(2w ago)0471MITPHPPHP ^8.2CI passing

Since Jan 3Pushed 2w agoCompare

[ Source](https://github.com/znojil/heureka)[ Packagist](https://packagist.org/packages/znojil/heureka)[ RSS](/packages/znojil-heureka/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (4)Dependencies (10)Versions (6)Used By (1)

Znojil Heureka
==============

[](#znojil-heureka)

[![Latest Stable Version](https://camo.githubusercontent.com/ad7de1110927f4cc083cbec15b5970a872b987a966dfe7e41a2ea488aad2e3e4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a6e6f6a696c2f68657572656b61)](https://packagist.org/packages/znojil/heureka)[![PHP Version Require](https://camo.githubusercontent.com/6186bb2bd0859862b5058016ce6a2ca5b490d25351fca4609dfb9f839a983ebe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7a6e6f6a696c2f68657572656b612f706870)](https://packagist.org/packages/znojil/heureka)[![License](https://camo.githubusercontent.com/d74c1be3d43b3ee784d0e4007299737d3ea29e310b887ed2a3b9256a82bbe12a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7a6e6f6a696c2f68657572656b61)](LICENSE)[![Tests](https://github.com/znojil/heureka/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/znojil/heureka/actions/workflows/tests.yml)

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
-------------------

[](#-supported-regions)

This library supports the following regions:

- Heureka.cz
- Heureka.sk

🔑 Service Activation
--------------------

[](#-service-activation)

To use the `Verified by Customers` (Ověřeno zákazníky) service, you must first [activate it here](https://sluzby.heureka.cz/napoveda/overeno-jak-aktivovat/).

🚀 Installation
--------------

[](#-installation)

Install the library using Composer:

```
composer require znojil/heureka
```

📖 Usage
-------

[](#-usage)

### 1. Client Initialization

[](#1-client-initialization)

First, you need to create a client instance. The client requires a region (`.cz` or `.sk`) and an [API key](https://sluzby.heureka.cz/sluzby/certifikat-spokojenosti/) 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

[](#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

[](#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

[](#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

[](#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)

[](#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: 'customer@email.com',
	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](https://github.com/heureka/overeno-zakazniky/blob/30eb6f7ab47ee3068f71efbdbde4a0d4b019a0a2/docs/api-documentation-en.md).

⚠️ Error Handling
-----------------

[](#️-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
---------

[](#-license)

This library is open-source software licensed under the [MIT license](https://choosealicense.com/licenses/mit/).

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance96

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~52 days

Total

5

Last Release

19d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6079815?v=4)[Marek Znojil](/maintainers/znojil)[@znojil](https://github.com/znojil)

---

Top Contributors

[![znojil](https://avatars.githubusercontent.com/u/6079815?v=4)](https://github.com/znojil "znojil (12 commits)")

---

Tags

apiheurekahttpovereno-zakaznikyphpapiclientsdkreviewsheurekaznojilovereno-zakazniky

###  Code Quality

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/znojil-heureka/health.svg)

```
[![Health](https://phpackages.com/badges/znojil-heureka/health.svg)](https://phpackages.com/packages/znojil-heureka)
```

###  Alternatives

[kunalvarma05/dropbox-php-sdk

Dropbox PHP API V2 SDK (Unofficial)

3613.2M19](/packages/kunalvarma05-dropbox-php-sdk)[jolicode/slack-php-api

An up to date PHP client for Slack's API

2554.9M13](/packages/jolicode-slack-php-api)[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

47394.5k5](/packages/deepseek-php-deepseek-php-client)[qwen-php/qwen-php-client

robust and community-driven PHP SDK library for seamless integration with the qwen AI API, offering efficient access to advanced AI and data processing capabilities

203.3k1](/packages/qwen-php-qwen-php-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)