marcingladkowski/gus-regon-bundle

Symfony bundle for GUS (Central Statistical Office) REGON API integration - Polish business registry lookup

0.5.1 2026-01-14 21:28 UTC

Requires

• php: >=8.2
• gusapi/gusapi: ^6.3
• psr/log: ^3.0
• symfony/cache: ^7.0
• symfony/config: ^7.0
• symfony/dependency-injection: ^7.0
• symfony/framework-bundle: ^7.0
• symfony/http-kernel: ^7.0
• symfony/yaml: ^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.92
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^12.0
• symfony/phpunit-bridge: ^7.0
• symfony/var-dumper: ^7.0

MIT

• Marcin Gladkowski

• symfony
• api
• bundle
• regon
• GUS
• poland
• business-registry

README

A Symfony bundle for integrating with the Polish GUS (Central Statistical Office) REGON API. This bundle provides easy access to business registry data for Polish companies.

Features

• 🔍 Business Lookup: Search for companies by NIP (Tax ID) or REGON number
• 📊 Complete Data: Retrieve comprehensive business information including addresses, PKD codes, and more
• ✅ Validation: Built-in NIP and REGON number validators
• 🚀 Easy Integration: Simple Symfony service integration
• 💾 Caching: Optional caching support for API responses
• 🔒 Type Safety: Full PHP 8.2+ type declarations and DTOs

Requirements

• PHP >= 8.2
• Symfony >= 7.0
• GUS API credentials (user key)

Installation

composer require marcingladkowski/gus-regon-bundle

Configuration

Register the bundle in your config/bundles.php:

return [
    // ...
    GusBundle\GusBundle::class => ['all' => true],
];

Configure your GUS API credentials in config/packages/gus.yaml:

gus:
    api_key: '%env(GUS_API_KEY)%'
    environment: 'production' # or 'test'
    cache:
        enabled: true
        ttl: 3600

Set your API key in .env:

GUS_API_KEY=your_gus_api_key_here

Usage

Basic Company Lookup

use GusBundle\Client\RegonClientInterface;
use GusApi\SearchReport;

class YourController
{
    public function __construct(
        private RegonClientInterface $gusClient
    ) {}

    public function lookup(string $nip): Response
    {
        $reports = $this->gusClient->getByNip($nip);
        
        foreach ($reports as $report) {
            /** @var SearchReport $report */
            $name = $report->getName();
            $regon = $report->getRegon();
            
            // ...
        }
    }
}

Data Transfer Objects

The bundle provides comprehensive DTOs for structured data:

• BusinessDataDTO: Main business entity data
• AddressDTO: Address information
• PkdCodeDTO: PKD (Polish Classification of Activities) codes

Testing

composer install
vendor/bin/phpunit

Documentation

For detailed documentation, see the docs directory:

• Example Companies Data
• Contributing Guide

License

MIT License. See LICENSE file for details.

Credits

Created by Marcin Gladkowski

Uses the gusapi/gusapi library for GUS API communication.

Support

• 🐛 Report Issues
• 💬 Discussions