PHPackages                             hrabo/ares-bundle - 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. hrabo/ares-bundle

ActiveSymfony-bundle[API Development](/categories/api)

hrabo/ares-bundle
=================

Symfony bundle for ARES (Administrativní registr ekonomických subjektů) REST API integration.

v0.1.0(2mo ago)02MITPHPPHP ^8.2 || ^8.3CI passing

Since Mar 4Pushed 2mo agoCompare

[ Source](https://github.com/hrabosh/ares-bundle)[ Packagist](https://packagist.org/packages/hrabo/ares-bundle)[ RSS](/packages/hrabo-ares-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (13)Versions (2)Used By (0)

LustraceAresBundle
==================

[](#lustracearesbundle)

Symfony bundle integrating the official **ARES (Administrativní registr ekonomických subjektů)** REST API.

The bundle focuses on:

- **Company detail by IČO** from ARES “core” and/or individual datasets (RES, VR, RŽP, ROS, RCNS, RPSH, CEÚ, RŠ, SZR, NRPZS).
- **Configurable retries** (HTTP client retry strategy + `Retry-After` support).
- **Configurable rate limiting** (token bucket limiter) to avoid API blocking.
- **Standardized output** (DTOs + `toArray()`).

> API documentation:
>
> - OpenAPI:
> - Swagger UI:
> - Developer info:
> - Technical doc (catalog of public services): [https://mf.gov.cz/assets/attachments/2024-02-16\_ARES-Technical-documentation-Catalog-of-public-services\_v02.pdf](https://mf.gov.cz/assets/attachments/2024-02-16_ARES-Technical-documentation-Catalog-of-public-services_v02.pdf)

---

Installation
------------

[](#installation)

```
composer require hrabo/ares-bundle
```

Enable the bundle (if not using Flex auto-discovery):

```
// config/bundles.php
return [
    // ...
    Hrabo\AresBundle\HraboAresBundle::class => ['all' => true],
];
```

---

Configuration
-------------

[](#configuration)

Create `config/packages/hrabo_ares.yaml`:

```
hrabo_ares:
  base_uri: 'https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/'
  timeout_seconds: 10

  retry:
    max_retries: 3
    delay_ms: 250
    multiplier: 2.0
    max_delay_ms: 5000
    jitter: 0.1
    status_codes: [0, 429, 500, 502, 503, 504]

  rate_limit:
    enabled: true
    # Token bucket limiter:
    limit: 10
    interval: '1 second'
    burst: 20
    wait: true
    key: 'ares-outgoing' # all workers share this key via cache.app

  datasets:
    # Default datasets used by findCompanyByIco() when not provided explicitly:
    - ares
    - res
    - vr
    - rzp
    - ros
    - rcns
    - rpsh
    - ceu
    - rs
    - szr
    - nrpzs
```

Notes:

- `rate_limit.key` is stored via `cache.app` and shared across workers/servers if `cache.app` uses a shared backend (Redis, Memcached, ...).
- For maximum safety against ARES blocking, prefer a shared cache backend for `cache.app` (Redis).

---

Usage
-----

[](#usage)

### 1) Aggregate lookup by IČO across datasets

[](#1-aggregate-lookup-by-ičo-across-datasets)

```
use Hrabo\AresBundle\Client\AresClientInterface;

final class SomeService
{
    public function __construct(private AresClientInterface $ares) {}

    public function run(): void
    {
        $result = $this->ares->findCompanyByIco('00006947'); // or '6947'
        $best = $result->company; // NormalizedCompany|null

        // Array for storage/export:
        $payload = $result->toArray();
    }
}
```

### 2) Single dataset detail (GET {ico})

[](#2-single-dataset-detail-get-ico)

```
use Hrabo\AresBundle\Enum\Dataset;

$datasetResult = $ares->getEconomicSubject('6947', Dataset::RES);

if ($datasetResult->isOk()) {
    $company = $datasetResult->company; // NormalizedCompany
    $raw = $datasetResult->raw;         // array
}
```

### 3) Search (POST vyhledat)

[](#3-search-post-vyhledat)

```
use Hrabo\AresBundle\Enum\Dataset;

$search = $ares->searchEconomicSubjects(Dataset::ARES, [
    'start' => 0,
    'pocet' => 10,
    'obchodniJmeno' => 'Ministerstvo financí',
]);

// $search is raw ARES response array.
```

### 4) Codebooks (POST vyhledat)

[](#4-codebooks-post-vyhledat)

```
$codebooks = $ares->searchCodebooks([
    'start' => 0,
    'pocet' => 50,
    'kodCiselniku' => 'PravniForma',
]);
```

### 5) Standardized addresses (POST vyhledat)

[](#5-standardized-addresses-post-vyhledat)

```
$addresses = $ares->searchStandardizedAddresses([
    'start' => 0,
    'pocet' => 10,
    'textovaAdresa' => 'Letenská 525/15, Praha 1',
]);
```

---

Error handling contract
-----------------------

[](#error-handling-contract)

- **Input validation**:
    - Invalid IČO causes an `InvalidArgumentException` from `IcoNormalizer::normalize()`.
- **GET (company detail)**:
    - `getEconomicSubject()` and `findCompanyByIco()` do **not** throw on HTTP/API failures.
    - They always return `DatasetResult` entries with `status`:
        - `ok` (HTTP 200)
        - `not_found` (HTTP 404)
        - `error` (transport issues, invalid responses, non-200/404)
- **POST endpoints (search/codebooks/addresses)**:
    - `searchEconomicSubjects()`, `searchCodebooks()`, `searchStandardizedAddresses()` throw `AresApiException` on non-200 responses or invalid responses.
- **Rate limiting**:
    - If rate limiting is enabled and `wait=false`, the client may throw `AresRateLimitExceededException`.

---

Standardized output
-------------------

[](#standardized-output)

- `CompanyLookupResult` contains:
    - `icoCanonical` (8 digits, left padded with zeros)
    - `company` (first successful `NormalizedCompany` in chosen dataset order)
    - `datasets` map: dataset code → `DatasetResult`

---

Development
-----------

[](#development)

### Quality checks (PHPCS + PHPStan)

[](#quality-checks-phpcs--phpstan)

This project uses:

- **PHPCS** (Symfony coding standard) for code style
- **PHPStan** for static analysis

```
# run everything (style + static analysis)
composer check

# style only
composer phpcs

# auto-fix style (what can be fixed automatically)
composer phpcbf

# static analysis only
composer phpstan
```

Config files:

- PHPCS ruleset: `phpcs.xml`
- PHPStan config: `phpstan.neon`

---

Tests
-----

[](#tests)

```
composer install
vendor/bin/phpunit
```

---

Code style (phpcs/phpcbf)
-------------------------

[](#code-style-phpcsphpcbf)

```
# show violations
vendor/bin/phpcs

# auto-fix what can be fixed
vendor/bin/phpcbf
```

The ruleset is in `phpcs.xml` and uses the Symfony PHP\_CodeSniffer standard.

---

Versioning
----------

[](#versioning)

This is an initial bundle skeleton intended to be extended inside your application. PRs welcome.

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance85

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 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

76d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/079a4a09c462da6869d421f768c53d99b9325b9c897879385ac361d31398afbc?d=identicon)[hrabosh](/maintainers/hrabosh)

---

Top Contributors

[![hrabosh](https://avatars.githubusercontent.com/u/15844896?v=4)](https://github.com/hrabosh "hrabosh (5 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/hrabo-ares-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/hrabo-ares-bundle/health.svg)](https://phpackages.com/packages/hrabo-ares-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[simplesamlphp/simplesamlphp

A PHP implementation of a SAML 2.0 service provider and identity provider.

1.1k12.4M193](/packages/simplesamlphp-simplesamlphp)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)

PHPackages © 2026

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