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.0.0(4mo ago)0281MITPHPPHP ^8.2CI passing

Since Jan 3Pushed 3mo agoCompare

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

READMEChangelog (1)Dependencies (5)Versions (2)Used By (1)

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

[](#znojil-heureka)

[![Latest Stable Version](https://camo.githubusercontent.com/524eb7b1dc207889332241843605de6159f826122a7f2a51447ce117aab2feb6/68747470733a2f2f706f7365722e707567782e6f72672f7a6e6f6a696c2f68657572656b612f762f737461626c65)](https://github.com/znojil/heureka/releases)[![PHP Version Require](https://camo.githubusercontent.com/9f9ddf0b1e48f66674ecbe8379a00bca66477c39f823bb5b6fa7c8a04f01d1cc/68747470733a2f2f706f7365722e707567782e6f72672f7a6e6f6a696c2f68657572656b612f726571756972652f706870)](https://packagist.org/packages/znojil/heureka)[![License](https://camo.githubusercontent.com/5ed2375ac78504be64abd1b03ec8387247ebb3d2bc8a8d43ef4f67084c6bc24c/68747470733a2f2f706f7365722e707567782e6f72672f7a6e6f6a696c2f68657572656b612f6c6963656e7365)](LICENSE)[![Tests](https://github.com/znojil/heureka/actions/workflows/tests.yml/badge.svg)](https://github.com/znojil/heureka/actions)

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 logic to send the request...
		// For example, using Guzzle:
		// $guzzleClient = new \GuzzleHttp\Client;
		// return $guzzleClient->request($method, $uri, [...]);
	}
}

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

### 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 on failed HTTP requests to help you identify the issue:

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

📄 License
---------

[](#-license)

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

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance77

Regular maintenance activity

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

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

Unknown

Total

1

Last Release

129d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/346e196c4f9c654a246386453834885843c3cf8578883c1a9b82adfd3231bd09?d=identicon)[znojil](/maintainers/znojil)

---

Top Contributors

[![znojil](https://avatars.githubusercontent.com/u/6079815?v=4)](https://github.com/znojil "znojil (3 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)

3633.0M18](/packages/kunalvarma05-dropbox-php-sdk)[jolicode/slack-php-api

An up to date PHP client for Slack's API

2534.4M12](/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.

47073.9k5](/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

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

PHPackages © 2026

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