PHPackages                             znojil/nette-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/nette-heureka

ActiveLibrary[API Development](/categories/api)

znojil/nette-heureka
====================

🧩 Nette DI extension for the Heureka API library.

v1.0.0(5mo ago)00MITPHPPHP ^8.2CI passing

Since Jan 11Pushed 5mo agoCompare

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

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

Heureka API for Nette Framework
===============================

[](#heureka-api-for-nette-framework)

[![Latest Stable Version](https://camo.githubusercontent.com/0aea881b43ecdad6909ff7e6b4e551cc0e17610fb36232a8907d619e2cda646d/68747470733a2f2f706f7365722e707567782e6f72672f7a6e6f6a696c2f6e657474652d68657572656b612f762f737461626c65)](https://github.com/znojil/nette-heureka/releases)[![PHP Version Require](https://camo.githubusercontent.com/b83d77496e1508a84b5a12526e728dda10964a9784a6c6c45edb3782fcfe053a/68747470733a2f2f706f7365722e707567782e6f72672f7a6e6f6a696c2f6e657474652d68657572656b612f726571756972652f706870)](https://packagist.org/packages/znojil/nette-heureka)[![License](https://camo.githubusercontent.com/8a7e31bcdb12e1f09751b49906b239175714a80ae76021b35e8f710c4a59c759/68747470733a2f2f706f7365722e707567782e6f72672f7a6e6f6a696c2f6e657474652d68657572656b612f6c6963656e7365)](LICENSE)[![Tests](https://github.com/znojil/nette-heureka/actions/workflows/tests.yml/badge.svg)](https://github.com/znojil/nette-heureka/actions)

A simple Nette DI extension for the `znojil/heureka` PHP client, allowing for easy integration and configuration of one or more API clients.

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

[](#-installation)

Install via Composer:

```
composer require znojil/nette-heureka
```

⚙️ Configuration
----------------

[](#️-configuration)

First, register the extension in your `config.neon`:

```
extensions:
	heureka: Znojil\Nette\Heureka\DI\HeurekaExtension
```

### Single Client Setup

[](#single-client-setup)

If you only need to communicate with one Heureka region, you can configure a single client. This client service (`Znojil\Heureka\Client`) will be registered and autowired by the Nette DI container.

```
heureka:
	region: cz
	key: 'your-secret-api-key'
```

**Configuration options:**

- `region`: (required) The Heureka region to use. The value must be one of the cases in `Znojil\Heureka\Enum\Region`.
- `key`: (optional) Your API key for authenticated requests.
- `httpClient`: (optional) A custom HTTP client implementing `Znojil\Heureka\Http\Client` (e.g., `@myCustomHttpClient`).

### Multiple Clients Setup

[](#multiple-clients-setup)

If you need to work with multiple regions or API keys, you can configure multiple named clients.

```
heureka:
	cz_shop:
		region: cz
		key: 'your-main-cz-api-key'
	sk_shop:
		region: sk
		key: 'your-sk-subsidiary-api-key'
	cz_shop_no_key:
		region: cz
```

In this setup, a single `Znojil\Nette\Heureka\ClientProvider` service is registered. Individual clients are not autowired.

🛠️ Advanced Configuration
-------------------------

[](#️-advanced-configuration)

### Custom HTTP Client

[](#custom-http-client)

You can provide a custom HTTP client that implements the `Znojil\Heureka\Http\Client` interface. This interface requires PSR-7 compatibility (`Psr\Http\Message\ResponseInterface` and `UriInterface`) but is **not** PSR-18.

The interface signature:

```
interface Client{

	function send(
		string $method,
		Message\UriInterface $uri,
		array $headers = [],
		mixed $data = null,
		array $options = []
	): Message\ResponseInterface;

}
```

This is useful for adding custom headers, timeouts, proxy settings, or other HTTP-specific configuration.

#### Using an Existing Service

[](#using-an-existing-service)

Reference an existing service by name using the `@` prefix:

```
services:
	myCustomHttpClient: Your\Custom\HttpClient

heureka:
	region: cz
	key: 'your-api-key'
	httpClient: @myCustomHttpClient
```

#### Using a Class Name (Auto-instantiated)

[](#using-a-class-name-auto-instantiated)

Provide a fully qualified class name as a string:

```
heureka:
	region: cz
	key: 'your-api-key'
	httpClient: Your\Custom\HttpClient
```

#### Configuring HTTP Client with Inline Service Definitions

[](#configuring-http-client-with-inline-service-definitions)

You can configure any HTTP client directly in your NEON configuration using Nette DI's inline service definitions. This example demonstrates the approach using the default implementation (`Znojil\Heureka\Http\ZnojilClient`), but the same technique works with any custom client.

**Example: Custom User-Agent and Timeouts**

```
parameters:
	curlOptMap:
		userAgent: ::CURLOPT_USERAGENT
		timeout: ::CURLOPT_TIMEOUT
		connectTimeout: ::CURLOPT_CONNECTTIMEOUT

services:
	myCustomHttpClient: Znojil\Heureka\Http\ZnojilClient(
		Znojil\Http\Client(
			defaultCurlOptions: [
				%curlOptMap.userAgent%: 'MyApp/1.0 (Heureka Integration)'
				%curlOptMap.timeout%: 30
				%curlOptMap.connectTimeout%: 10
			]
		)
	)

heureka:
	region: cz
	key: 'your-api-key'
	httpClient: @myCustomHttpClient
```

**Why use parameter mapping?**

The `parameters.curlOptMap` approach is necessary because NEON's `::CONSTANT_NAME` syntax works only for **values**, not for **array keys**. Since cURL options require constants as keys (e.g., `CURLOPT_USERAGENT => 'value'`), we use parameter mapping to work around this limitation.

**How it works:**

1. Define constants in `parameters` section: `userAgent: ::CURLOPT_USERAGENT` (value position - works!)
2. Reference them as keys using `%curlOptMap.userAgent%` (expands to the constant value)

This keeps your configuration readable and type-safe while leveraging cURL's native options without resorting to magic numbers.

📖 Usage
-------

[](#-usage)

### Single Client

[](#single-client)

When using the single client setup, you can inject the `Znojil\Heureka\Client` directly into your services.

```