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: https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/v3/api-docs
• Swagger UI: https://ares.gov.cz/swagger-ui/
• Developer info: https://ares.gov.cz/stranky/vyvojar-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

---

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

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

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

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)

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)

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

5) Standardized addresses (POST vyhledat)

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

---

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

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

---

Development

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

composer install
vendor/bin/phpunit

---

Code style (phpcs/phpcbf)

# 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

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