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. 0.0.6.x-dev(2w ago)07MITPHPPHP ^8.2CI passing Since Apr 24Pushed 2w 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 1w ago READMEChangelogDependencies (11)Versions (7)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 - Pest test suite, PHPStan configuration, and GitHub Actions CI Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 10, 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_ttl``86400`Cache lifetime for successful lookups in seconds`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 secondsEnvironment overrides: - `ARES_API_URL` - `ARES_CACHE_TTL` - `ARES_LOG_CHANNEL` - `ARES_HTTP_TIMEOUT` - `ARES_HTTP_CONNECT_TIMEOUT` 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` 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 `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` Artisan Command --------------- [](#artisan-command) The package includes an artisan helper for manual verification: ``` php artisan ares:test 27074358 ``` The command 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: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`. License ------- [](#license) The package is open-sourced under the [MIT license](LICENSE). ### Health Score 38 — LowBetter than 83% of packages Maintenance96 Actively maintained with recent releases Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity36 Early-stage or recently created project 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 ~5 days Total 6 Last Release 20d ago 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 3325.1M337](/packages/psalm-plugin-laravel)[spatie/laravel-export Create a static site bundle from a Laravel app 670139.5k6](/packages/spatie-laravel-export)[defstudio/telegraph A laravel facade to interact with Telegram Bots 815320.5k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof. 5019.3k](/packages/simplestats-io-laravel-client)[tallstackui/tallstackui TallStackUI is a powerful suite of Blade components that elevate your workflow of Livewire applications. 719160.4k12](/packages/tallstackui-tallstackui)[fleetbase/core-api Core Framework and Resources for Fleetbase API 1232.2k16](/packages/fleetbase-core-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)