# Laravel BIR REGON

> `cieplik206/laravel-bir-regon` is a Laravel 12 and 13 package for the Polish GUS BIR/REGON SOAP API. It provides fluent facade and dependency-injection workflows for NIP, REGON, and KRS searches, batch lookups, full and bulk reports, service diagnostics, and typed `spatie/laravel-data` results. It requires PHP 8.3 or newer with SOAP and SimpleXML, and its compatibility matrix covers both Laravel releases on PHP 8.3, 8.4, and 8.5.

Keep identifiers as strings to preserve leading zeroes. Use the package enums for report types, use `BirRegon::sandbox()` for the GUS test service, and keep SOAP authentication and session handling inside the package.

## Getting Started

- [Online Documentation](https://cieplik206.github.io/laravel-bir-regon/): Rendered guides and API usage documentation.
- [Installation](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/installation.md): Requirements, Composer installation, Laravel package discovery, configuration publishing, and optional Boost setup.
- [Configuration](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/configuration.md): Separate production and sandbox credentials, sandbox selection, reusable sessions, and Laravel configuration-cache guidance.
- [Basic Usage](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/basic-usage.md): Idiomatic facade and dependency-injection examples for single searches and typed results.

## Core Concepts

- [Batch Searches](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/batch-searches.md): Batch methods, identifier formats, the 20-item GUS limit, collection results, and chunking guidance.
- [Full and Bulk Reports](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/reports.md): Fluent report workflows, every supported report enum, result shapes, and report applicability rules.
- [Service Status and Diagnostics](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/service-status-and-diagnostics.md): Public availability checks, authenticated data status, and production or sandbox session diagnostics.

## Reference and Integration

- [Data Objects](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/data-objects.md): Typed fields and serialization behavior for company, report, status, and diagnostic responses.
- [Error Handling](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/error-handling.md): Package exception hierarchy, catch order, wrapped upstream errors, and post-failure diagnostics.
- [Testing](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/testing.md): Isolated Pest and Testbench tests, static analysis, opt-in live GUS sandbox checks, and consumer fakes.
- [Extending the Package](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/extending.md): Replacing the public client or GUS API factory while preserving the facade and fluent API.

## AI Agent Guidance

- [Laravel Boost Skill](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/resources/boost/skills/bir-regon-development/SKILL.md): Authoritative package-specific instructions for agents implementing searches, reports, diagnostics, testing, or custom clients.
- [Laravel Boost Integration](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/docs/laravel-boost.md): How consuming applications discover, install, and update the optional package skill.

## Optional

- [Changelog](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/CHANGELOG.md): Released and unreleased package changes.
- [Security Policy](https://raw.githubusercontent.com/cieplik206/laravel-bir-regon/main/SECURITY.md): Supported versions, credential-handling rules, and the private vulnerability-reporting channel.
- [Source Repository](https://github.com/cieplik206/laravel-bir-regon): Canonical repository for source code, issues, releases, and deeper implementation details.