nks-hub / nette-ares
Nette extension for Czech ARES API — company lookup by IČO, search by name, structured results with caching. PHP 8.1+.
Requires
- php: >=8.1
- nette/caching: ^3.2 || ^4.0
- nette/di: ^3.1 || ^4.0
- nette/schema: ^1.2 || ^2.0
- nette/utils: ^3.2 || ^4.0
Requires (Dev)
- nette/tester: ^2.5
- phpstan/phpstan: ^1.10
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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
AresResultwith 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, unknown or malformed IČO and throws when ARES cannot be reached - 🔢 IČO checksum -
AresClient::isValidIco()verifies the modulo 11 check digit without a network call - 🎯 Nette integration - DI extension registered through
extra.nette.extensionsincomposer.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
try { echo $this->ares->isActive('27074358') ? 'Company is active' : 'Company is dissolved or unknown'; } catch (AresException $e) { echo 'ARES is unavailable, try again later'; }
isActive() returns false only when ARES answers that the IČO is unknown (HTTP 404), the IČO is malformed, or the company has a dissolution date. A connection failure, a timeout or an HTTP 5xx answer throws AresException, so an outage is never reported as a dissolved company. The "not found" exception has code 404; other API errors carry the HTTP status code.
Validate the IČO checksum
AresClient::isValidIco('27074358'); // true AresClient::isValidIco('27074359'); // false
findByIco() checks only the format (8 digits after padding), so it still asks ARES about numbers with a wrong check digit. Call isValidIco() first to reject typos without a request.
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',
'pravniForma' => '121',
'isPhysicalPerson' => false,
]
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ČOPOST /ekonomicke-subjekty/vyhledat: search by name
ARES requires no authentication. Keep caching on.
Development
Tests use Nette Tester and mock the HTTP layer, so they run offline:
composer install
composer test
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