README

Nette DI extension for ARES (the Czech Administrative Register of Economic Subjects): company lookup by IČO and by name, with cached results. PHP 8.1+.

Features

🔍 Lookup by IČO - Returns an AresResult with address, VAT ID (DIČ) and legal form
📝 Search by name - Returns up to limit (default 10) matching companies; the name needs at least 3 characters
💾 Caching - Results are cached for cacheTtl (default 1 month) and can be cleared per IČO
✅ Activity check - isActive() returns false for a dissolved or unknown company
🎯 Nette integration - DI extension registered through extra.nette.extensions in composer.json
🛡️ Strict types - Every source file declares strict_types=1; result properties are typed

Requirements

PHP 8.1+
Nette 3.1+ / 4.0+

Installation

composer require nks-hub/nette-ares

Configuration

Nette picks the extension up from extra.nette.extensions in composer.json. To register it manually in config.neon:

extensions:
    ares: NksHub\NetteAres\DI\AresExtension

Optional configuration:

ares:
    cacheTtl: '1 month'   # How long to cache results (default: 1 month)

Usage

Look up a company by IČO

use NksHub\NetteAres\AresClient;
use NksHub\NetteAres\AresException;

class MyPresenter extends Nette\Application\UI\Presenter
{
    public function __construct(
        private AresClient $ares,
    ) {}

    public function actionDetail(string $ico): void
    {
        try {
            $result = $this->ares->findByIco($ico);

            echo $result->obchodniJmeno;      // "Asseco Central Europe, a.s."
            echo $result->ico;                 // "27074358"
            echo $result->dic;                 // "CZ27074358"
            echo $result->getStreet();         // "Budějovická 778/3a"
            echo $result->getCity();           // "Praha - Michle"
            echo $result->getFormattedPsc();   // "140 00"
            echo $result->kodStatu;            // "CZ"

        } catch (AresException $e) {
            $this->flashMessage($e->getMessage(), 'danger');
        }
    }
}

Search companies by name

$results = $this->ares->searchByName('Asseco', limit: 5);

foreach ($results as $result) {
    echo "{$result->obchodniJmeno} (IČO: {$result->ico})\n";
}

Check whether a company is active

if ($this->ares->isActive('27074358')) {
    echo 'Company is active';
}

Get the VAT ID (DIČ)

$dic = $this->ares->getDic('27074358'); // "CZ27074358" or null

Use in an AJAX handler (typically for forms)

public function handleAresLookup(string $ico): void
{
    try {
        $result = $this->ares->findByIco($ico);
        $this->sendJson($result->toArray());
    } catch (AresException $e) {
        $this->sendJson(['error' => $e->getMessage()]);
    }
}

toArray() returns:

[
    'ico'            => '27074358',
    'dic'            => 'CZ27074358',
    'company'        => 'Asseco Central Europe, a.s.',
    'street'         => 'Budějovická 778/3a',
    'city'           => 'Praha - Michle',
    'zip'            => '140 00',
    'country'        => 'CZ',
    'textovaAdresa'  => 'Budějovická 778/3a, Michle, 14000 Praha 4',
]

Cache

Results stay cached for cacheTtl (default 1 month). To invalidate them:

$this->ares->clearCacheByIco('27074358'); // a specific IČO
$this->ares->clearCache();                 // the whole ARES cache

AresResult

Property	Type	Description
`ico`	`string`	IČO (8 digits)
`dic`	`?string`	DIČ (format CZ + IČO)
`obchodniJmeno`	`string`	Business name
`pravniForma`	`?string`	Legal form code
`ulice`	`?string`	Street name
`cisloDomovni`	`?int`	Building number (číslo popisné)
`cisloOrientacni`	`?int`	Orientation number (číslo orientační)
`mesto`	`?string`	Municipality
`castObce`	`?string`	Municipality part
`psc`	`?int`	Postal code (PSČ)
`kodStatu`	`?string`	Country code
`textovaAdresa`	`?string`	Full address as text
`datumVzniku`	`?string`	Date of establishment
`datumZaniku`	`?string`	Date of dissolution

Helper methods: getStreet(), getCity(), getFormattedPsc(), toArray().

API

The extension calls the ARES REST API v3:

GET /ekonomicke-subjekty/{ico}: lookup by IČO
POST /ekonomicke-subjekty/vyhledat: search by name

ARES requires no authentication and has no rate limit. Keep caching on anyway.

Development

There is no test suite. Validate the package manifest with:

composer validate

Contributing

Contributions are welcome! For major changes, please open an issue first.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: description')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

📧 Email: dev@nks-hub.cz
🐛 Bug reports: GitHub Issues
📖 ARES API docs: ares.gov.cz

License

MIT License — see LICENSE for details.

Made with ❤️ by NKS Hub

nks-hub / nette-ares

Package info

Security

Statistics