PHPackages nyoncode/laravel-ares - 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. nyoncode/laravel-ares ActiveLibrary[API Development](/categories/api) nyoncode/laravel-ares ===================== Laravel package for the Czech ARES business register API with caching, events, validation and artisan tooling. 1.1.0(3w ago)09MITPHPPHP ^8.2CI passing Since Apr 24Pushed 2mo agoCompare [ Source](https://github.com/NyonCode/laravel-ares)[ Packagist](https://packagist.org/packages/nyoncode/laravel-ares)[ RSS](/packages/nyoncode-laravel-ares/feed)WikiDiscussions main Synced 3w ago READMEChangelog (2)Dependencies (21)Versions (11)Used By (0) laravel-ares ============ [](#laravel-ares) `laravel-ares` is a Laravel package for the Czech ARES business register API. It provides a typed client, a facade, configurable caching, lookup events, ICO validation, static analysis support, and an artisan command for diagnostics. Features -------- [](#features) - Typed public API through `AresClientInterface` - `Ares` facade with convenience methods for common workflows - Structured domain objects instead of one large flat payload object - Configurable caching and HTTP timeouts - Events for successful and failed lookups - ICO normalization and checksum validation - Explicit exceptions for invalid ICO and missing companies - Subject indexing with database-backed autocomplete search - Pest test suite, PHPStan configuration, and GitHub Actions CI Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11, 12, or 13 Installation ------------ [](#installation) Install the package with Composer: ``` composer require nyoncode/laravel-ares ``` Publish the configuration file if you want local overrides: ``` php artisan vendor:publish --tag=laravel-ares::config ``` Configuration ------------- [](#configuration) KeyDefaultDescription`api_url``https://ares.gov.cz/ekonomicke-subjekty-v-be/rest`Base URL for the ARES REST API`cache.enabled``true`Enable response caching; set to `false` to disable caching entirely`cache.ttl``86400`Cache lifetime for successful lookups in seconds`cache.store``null`Cache store to use (`null` = default store)`cache.prefix``ares:v1:company:`Prefix for ARES cache keys`log_channel``stack`Laravel log channel used for client errors`http_options.timeout``5.0`Request timeout in seconds`http_options.connect_timeout``3.0`Connection timeout in seconds`indexing.enabled``true`Enable subject indexing and search`indexing.auto_index``true`Automatically index subjects on successful lookup`indexing.stale_days``30`Number of days before a record is considered staleEnvironment overrides: - `ARES_API_URL` - `ARES_CACHE_ENABLED` - `ARES_CACHE_TTL` - `ARES_CACHE_STORE` - `ARES_CACHE_PREFIX` - `ARES_LOG_CHANNEL` - `ARES_HTTP_TIMEOUT` - `ARES_HTTP_CONNECT_TIMEOUT` - `ARES_INDEXING_ENABLED` - `ARES_AUTO_INDEX` - `ARES_STALE_DAYS` Usage ----- [](#usage) Use dependency injection when you want explicit contracts: ``` use NyonCode\Ares\Contracts\AresClientInterface; final class CompanyLookupService { public function __construct( private readonly AresClientInterface $ares, ) {} public function companyName(string $ic): ?string { return $this->ares->findCompany($ic)?->name; } } ``` Use the facade for concise application code: ``` use NyonCode\Ares\Facades\Ares; $normalizedIc = Ares::normalizeIc('27 074 358'); $company = Ares::findCompanyOrFail($normalizedIc); dump($company->name); dump($company->registeredOffice?->formatted); dump($company->registration->naceCodes); ``` Public API: - `findCompany(string $ic): ?CompanyData` - `findCompanyRaw(string $ic): ?array` - `findCompanyOrFail(string $ic): CompanyData` - `forgetCompany(string $ic): bool` - `isValidIc(string $ic): bool` - `normalizeIc(string $ic): string` - `search(string $query, int $limit = 10): Collection` Domain Model ------------ [](#domain-model) Successful lookups return `NyonCode\Ares\Data\CompanyData`: ``` final class CompanyData { public readonly string $ic; public readonly string $name; public readonly ?string $dic; public readonly ?string $dicSkDph; public readonly ?AddressData $registeredOffice; public readonly ?DeliveryAddressData $deliveryAddress; public readonly RegistrationData $registration; public readonly array $rawData; } ``` Related DTOs: - `AddressData` models the registered office - `DeliveryAddressData` models the mailing address - `RegistrationData` groups legal form, dates, source, file mark, NACE codes, and source statuses - `RegistrationStatusData` represents one registry source status - `RegistrationSourceState` is a typed enum for known ARES status values - `SubjectData` is a lightweight DTO for autocomplete search results (`ic`, `name`, `city`) `rawData` remains available as an escape hatch for fields the package does not map yet. Exceptions ---------- [](#exceptions) The fail-fast API throws explicit domain exceptions: - `NyonCode\Ares\Exceptions\InvalidIcException` - `NyonCode\Ares\Exceptions\CompanyNotFoundException` Malformed payloads are treated as failed lookups internally and surface through the failure event path. Events ------ [](#events) The package dispatches: - `NyonCode\Ares\Events\CompanyLookupSucceeded` - `NyonCode\Ares\Events\CompanyLookupFailed` Subject Indexing and Autocomplete --------------------------------- [](#subject-indexing-and-autocomplete) The package can index looked-up subjects into a local database table for fast autocomplete search. Run the migration after installing: ``` php artisan migrate ``` Search indexed subjects by name or IC: ``` // Search by company name $results = Ares::search('Asseco'); // Search by IC prefix $results = Ares::search('2707', 5); // Using the global helper $results = ares_search('Skoda'); ``` Each result is a `SubjectData` with `ic`, `name`, and `city` properties. ### Auto-indexing [](#auto-indexing) When `indexing.auto_index` is enabled (default), every successful `findCompany()` call dispatches a queued job that indexes the subject automatically. No extra code needed. ### Manual Indexing [](#manual-indexing) ``` # Index specific subjects php artisan ares:index 27074358 25596641 # Refresh stale records (older than configured stale_days) php artisan ares:index --refresh-stale # Custom stale threshold and limit php artisan ares:index --refresh-stale --stale-days=14 --limit=200 ``` Schedule the refresh in your application's scheduler for automatic maintenance: ``` $schedule->command('ares:index --refresh-stale')->daily(); ``` Artisan Commands ---------------- [](#artisan-commands) The package includes artisan commands for diagnostics and indexing: ``` # Test ARES API connectivity php artisan ares:test 27074358 # Index subjects php artisan ares:index 27074358 # Show indexing statistics php artisan ares:index # Refresh stale records php artisan ares:index --refresh-stale ``` `ares:test` renders a compact company summary including DIC, source, dates, registered office, delivery address, and register metadata. Quality Gates ------------- [](#quality-gates) Run the automated tests: ``` composer test ``` Run static analysis: ``` composer analyse ``` Run the formatter: ``` composer format ``` The repository includes a GitHub Actions workflow for: - PHP/Laravel compatibility matrix tests - PHPStan on the quality lane - Pint on the quality lane Development Notes ----------------- [](#development-notes) - Successful lookups are cached under the `ares:v1:company:{ic}` key format. - Invalid ICO values are rejected before any HTTP request is sent. - `forgetCompany()` invalidates cache entries using normalized ICO values. - Failed HTTP responses, malformed payloads, and transport exceptions all dispatch `CompanyLookupFailed`. - Auto-indexed subjects are stored in the `ares_subjects` table with a minimal footprint (`ic`, `name`, `city`, `indexed_at`). - Search uses `LIKE` queries with database indexes for fast prefix/substring matching. License ------- [](#license) The package is open-sourced under the [MIT license](LICENSE). ### Health Score 41 — FairBetter than 87% of packages Maintenance91 Actively maintained with recent releases Popularity5 Limited adoption so far Community6 Small or concentrated contributor base Maturity53 Maturing project, gaining track record 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 Every ~7 days Recently: every ~0 days Total 10 Last Release 24d ago Major Versions 0.0.6.x-dev → 1.0.02026-06-30 PHP version history (2 changes)0.0.1.x-devPHP ^8.1 0.0.2.x-devPHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/f9584d2f81e9fbaa694ea06ab95ab9fcf7bb309201cba5b1dab1fc88d7cd3eb9?d=identicon)[NyonCode](/maintainers/NyonCode) --- Top Contributors [![ONyklicek](https://avatars.githubusercontent.com/u/60318239?v=4)](https://github.com/ONyklicek "ONyklicek (31 commits)") ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/nyoncode-laravel-ares/health.svg) ``` [![Health](https://phpackages.com/badges/nyoncode-laravel-ares/health.svg)](https://phpackages.com/packages/nyoncode-laravel-ares) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5022.6k](/packages/simplestats-io-laravel-client)[defstudio/telegraph A laravel facade to interact with Telegram Bots 813336.8k3](/packages/defstudio-telegraph)[tallstackui/tallstackui TallStackUI is a powerful suite of Blade components that elevate your workflow of Livewire applications. 728176.2k14](/packages/tallstackui-tallstackui)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9762.4M133](/packages/roots-acorn) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)