README

Nette DI extension pro ARES (Administrativní registr ekonomických subjektů) — vyhledávání firem podle IČO i názvu s automatickým cachováním výsledků. PHP 8.1+.

Features

• 🔍 Vyhledání podle IČO — strukturovaný výsledek s adresou, DIČ, právní formou
• 📝 Fulltextové vyhledávání — hledání firem podle názvu s limitem výsledků
• 💾 Automatické cachování — konfigurovatelný TTL (výchozí 1 měsíc)
• ✅ Kontrola aktivity — ověření, zda firma není zaniklá
• 🎯 Nette integrace — DI extension s auto-registrací přes composer.json
• 🛡️ Type-safe — PHP 8.1+ s strict types a typed properties

Requirements

• PHP 8.1+
• Nette 3.1+ / 4.0+

Instalace

composer require nks-hub/nette-ares

Registrace

Extension se registruje automaticky díky extra.nette.extensions v composer.json.

Ruční registrace v config.neon:

extensions:
    ares: NksHub\NetteAres\DI\AresExtension

Konfigurace (volitelná)

ares:
    cacheTtl: '1 month'   # Jak dlouho cachovat výsledky (výchozí: 1 month)

Použití

Vyhledání firmy podle 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');
        }
    }
}

Vyhledání firem podle názvu

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

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

Kontrola aktivity firmy

if ($this->ares->isActive('27074358')) {
    echo 'Firma je aktivní';
}

Získání DIČ

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

Použití v AJAX handleru (typicky pro formuláře)

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() vrací:

[
    '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

Výsledky se automaticky cachují (výchozí: 1 měsíc). Manuální invalidace:

$this->ares->clearCacheByIco('27074358'); // konkrétní IČO
$this->ares->clearCache();                 // celý ARES cache

AresResult

Objekt AresResult obsahuje:

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

API

Extension využívá oficiální ARES REST API v3:

• GET /ekonomicke-subjekty/{ico} — vyhledání podle IČO
• POST /ekonomicke-subjekty/vyhledat — fulltextové vyhledávání

Bez autentizace, bez rate-limitu ze strany ARES (doporučujeme rozumné cachování).

Testing

./vendor/bin/tester tests

Contributing

Pull requesty jsou vítány! Pro větší změny prosím nejprve otevřete issue.

1. Fork repozitáře
2. Vytvořte feature branch (git checkout -b feature/nova-funkce)
3. Commit změn (git commit -m 'feat: popis')
4. Push branch (git push origin feature/nova-funkce)
5. Otevřete Pull Request

Podpora

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

Licence

MIT License — viz LICENSE

Made with ❤️ by NKS Hub