Laravel BIR REGON requires:
ext-dom)ext-curl)ext-libxml)Composer installs illuminate/cache, illuminate/contracts, and
illuminate/support 13.x as runtime components. With the default request
limiter enabled, use the exact base Laravel cache repository with an
ArrayStore, DatabaseStore, FileStore, MemcachedStore, or RedisStore.
Other repositories and stores fail closed even when they expose an atomic-lock
API.
The Pest 5 matrix covers Laravel 13 on PHP 8.4 and 8.5. PHP 8.4 uses both the
lowest and highest resolvable test toolchains, while PHP 8.5 uses the highest
versions. A separate runtime-only Composer check resolves PHP 8.4.0 with
illuminate/cache, illuminate/contracts, and illuminate/support 13.0.
Applications that need PHP 8.3 or Laravel 12 must stay on the 1.x package line.
Composer verifies these extensions directly. Version 2 uses the package’s native, bounded cURL transport and strict XML decoders; it neither requires PHP’s SOAP extension nor installs a separate GUS API client library.
The native transport retains one cURL handle per sender instance so libcurl can reuse its HTTPS connection, DNS cache, and TLS session. Request bodies, callbacks, and SID headers are reset between calls, and production and sandbox never share a handle.
Install the current stable release with:
composer require cieplik206/laravel-bir-regon:^2.0
Laravel’s package discovery registers
cieplik206\BirRegon\BirRegonServiceProvider automatically. No changes to
bootstrap/providers.php are required.
Add your production BIR API key to .env:
BIR_API_KEY=your-api-key
The API key is required for searches, reports, the data-status endpoint, and diagnostics. Reading the public service status does not require authentication.
Never commit a real API key to the repository.
The package includes the public key for the official GUS sandbox. If GUS provides a different test key, configure it separately:
BIR_SANDBOX_API_KEY=your-test-key
The sandbox key is never used for production requests, and the production key is never sent to the sandbox endpoint.
Missing or malformed credentials are reported with an environment-specific
hint: configure BIR_API_KEY for production and BIR_SANDBOX_API_KEY for the
sandbox. The sandbox uses an independently maintained, mutable test dataset.
Records may be outdated, incomplete, artificial, or anonymized, so a sandbox
result must not be treated as evidence of the current production registry
state.
Identifier checksums are optional. To reject invalid NIP and REGON checksums locally for both environments, add:
BIR_IDENTIFIER_VALIDATION=checksum
The default format mode checks only the exact digit lengths required by GUS.
KRS has no checksum and is format-only in either mode.
When the application must reach GUS through a corporate proxy, configure its URL explicitly for both production and sandbox traffic:
BIR_PROXY_URL=https://proxy.example.com:8443
BIR_PROXY_USERNAME=proxy-user
BIR_PROXY_PASSWORD=proxy-password
BIR_PROXY_URL accepts an http or https proxy. The credentials are optional,
but the username and password must either both be present or both be absent and
are accepted only for https://. Anonymous http:// proxies remain supported;
authenticated ones fail before network access because their client-to-proxy
link would be unencrypted. Keep credentials outside source control.
The native sender continues to verify TLS for the GUS endpoint and requires
TLS 1.2 or newer. For an HTTPS proxy, it applies the same minimum and verifies
the proxy itself. See
Configuration for the URL rules, ambient
HTTPS_PROXY behavior, and custom-sender limitation.
Request limiting is enabled automatically by the Laravel service provider.
Queue workers or application instances on several hosts should point
BIR_RATE_LIMIT_STORE at the same shared Redis store:
BIR_RATE_LIMIT_STORE=redis
Install and configure the Redis client required by the consuming Laravel
application; this package does not choose one. ArrayStore and FileStore are
local and cannot coordinate separate hosts. Tagged caches, repository
decorators/subclasses, DynamoDB, FailoverStore, MemoizedStore, NullStore, and
custom stores are intentionally unsupported; provide a custom limiter when one
of those backends is required. The lock lease is 30 seconds and contention
waiting is bounded to one second. See
Request limits for the official schedules, batch weighting,
failure behavior, and all limiter variables.
Publishing is optional. The package defaults work directly from environment variables, but a published file makes the available settings visible in the application:
php artisan vendor:publish --tag=bir-regon-config
This creates config/bir-regon.php.
The package includes an optional bir-regon-development agent skill. If the
consuming application does not yet use Laravel Boost, install and configure it
first:
composer require laravel/boost --dev
php artisan boost:install
If Boost was installed before Laravel BIR REGON, discover newly installed package skills with:
php artisan boost:update --discover
Laravel Boost will offer to install the skill for the configured AI agents. The package does not require Laravel Boost at runtime. See Laravel Boost support for the skill’s scope and update workflow.
This is only necessary when package discovery is disabled in the consuming
application. Add the provider to bootstrap/providers.php:
<?php
use cieplik206\BirRegon\BirRegonServiceProvider;
return [
App\Providers\AppServiceProvider::class,
BirRegonServiceProvider::class,
];
Continue with Configuration.
Upgrading from 1.x? Follow the Upgrade guide for 2.0.