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

• 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

• PHP 8.2+
• Laravel 11, 12, or 13

Installation

Install the package with Composer:

1composer require nyoncode/laravel-ares

Publish the configuration file if you want local overrides:

1php artisan vendor:publish --tag=laravel-ares::config

Configuration

Environment 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

Use dependency injection when you want explicit contracts:

 1use NyonCode\Ares\Contracts\AresClientInterface;
 2 
 3final class CompanyLookupService
 4{
 5    public function __construct(
 6        private readonly AresClientInterface $ares,
 7    ) {}
 8 
 9    public function companyName(string $ic): ?string
10    {
11        return $this->ares->findCompany($ic)?->name;
12    }
13}

Use the facade for concise application code:

1use NyonCode\Ares\Facades\Ares;
2 
3$normalizedIc = Ares::normalizeIc('27 074 358');
4$company = Ares::findCompanyOrFail($normalizedIc);
5 
6dump($company->name);
7dump($company->registeredOffice?->formatted);
8dump($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<SubjectData>

Domain Model

Successful lookups return NyonCode\Ares\Data\CompanyData:

 1final class CompanyData
 2{
 3    public readonly string $ic;
 4    public readonly string $name;
 5    public readonly ?string $dic;
 6    public readonly ?string $dicSkDph;
 7    public readonly ?AddressData $registeredOffice;
 8    public readonly ?DeliveryAddressData $deliveryAddress;
 9    public readonly RegistrationData $registration;
10    public readonly array $rawData;
11}

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

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

The package dispatches:

• NyonCode\Ares\Events\CompanyLookupSucceeded
• NyonCode\Ares\Events\CompanyLookupFailed

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:

1php artisan migrate

Search indexed subjects by name or IC:

1// Search by company name
2$results = Ares::search('Asseco');
3 
4// Search by IC prefix
5$results = Ares::search('2707', 5);
6 
7// Using the global helper
8$results = ares_search('Skoda');

Each result is a SubjectData with ic, name, and city properties.

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

1# Index specific subjects
2php artisan ares:index 27074358 25596641
3 
4# Refresh stale records (older than configured stale_days)
5php artisan ares:index --refresh-stale
6 
7# Custom stale threshold and limit
8php artisan ares:index --refresh-stale --stale-days=14 --limit=200

Schedule the refresh in your application's scheduler for automatic maintenance:

1$schedule->command('ares:index --refresh-stale')->daily();

Artisan Commands

The package includes artisan commands for diagnostics and indexing:

 1# Test ARES API connectivity
 2php artisan ares:test 27074358
 3 
 4# Index subjects
 5php artisan ares:index 27074358
 6 
 7# Show indexing statistics
 8php artisan ares:index
 9 
10# Refresh stale records
11php 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

Run the automated tests:

1composer test

Run static analysis:

1composer analyse

Run the formatter:

1composer 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

• 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

The package is open-sourced under the MIT license.