PHPackages hyraiq/ie-companies-registration-office-lookup - 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. [Utility & Helpers](/categories/utility) 4. / 5. hyraiq/ie-companies-registration-office-lookup ActiveLibrary[Utility & Helpers](/categories/utility) hyraiq/ie-companies-registration-office-lookup ============================================== Irish business number validation and verification using the Irish Companies Registration Office (CRO) web services API 2.0.0(11mo ago)019.6k—0%MITPHPPHP >=8.1CI passing Since Jan 24Pushed 11mo ago2 watchersCompare [ Source](https://github.com/hyraiq/ie-companies-registration-office-lookup)[ Packagist](https://packagist.org/packages/hyraiq/ie-companies-registration-office-lookup)[ RSS](/packages/hyraiq-ie-companies-registration-office-lookup/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (22)Versions (3)Used By (0) hyraiq/ie-companies-registration-office-lookup ============================================== [](#hyraiqie-companies-registration-office-lookup) A PHP SDK to validate Irish Business Numbers and verify them with the [Irish Companies Registration Office (CRO) Public Data API](https://services.cro.ie/index.aspx). The difference between validation and verification can be outlined as follows: - Validation uses a regular expression to check that a given number is a valid Irish business number. This *does not* contact the API to ensure that the given number is assigned to a business - Verification contacts the Companies Registration Office through their API to retrieve information registered against the entity number. It will tell you if the number actually belongs to a business. In order to use the API (only necessary for verification), you'll need to [register an account](https://services.cro.ie/overview.aspx) to receive an API key. Type safety ----------- [](#type-safety) The SDK utilises the [Symfony Serializer](https://symfony.com/doc/current/components/serializer.html) and the [Symfony Validator](https://symfony.com/doc/current/components/validator.html) to deserialize and validate data returned from the API in order to provide a valid [IeCompanyResponse](./src/Model/IeCompanyResponse.php) model. This means that if you receive a response from the SDK, it is guaranteed to be valid. Invalid responses from the API fall into three categories, which are handled with exceptions: - `ConnectionException.php`: Unable to connect to the API, or the API returned an unexpected response - `NumberInvalidException.php`: The entity number is invalid (i.e. validation failed) - `NumberNotFoundException.php`: The entity number is valid, however it is not assigned to a business (i.e. verification failed) Usage ----- [](#usage) ### Installation [](#installation) ``` $ composer require hyraiq/ie-companies-registration-office-lookup ``` ### Configuration with Symfony [](#configuration-with-symfony) In `services.yaml`, you need to pass your CRO API key and associated email address to the `ApiClient` and register the `ApiClient` with the `ApiClientInterface`: ``` Hyra\IeCompaniesRegistrationOfficeLookup\ApiClientInterface: '@Hyra\IeCompaniesRegistrationOfficeLookup\ApiClient' Hyra\IeCompaniesRegistrationOfficeLookup\ApiClient: arguments: $email: "%env(IE_COMPANIES_REGISTRATION_OFFICE_API_KEY)%" $apiKey: "%env(IE_COMPANIES_REGISTRATION_OFFICE_EMAIL)%" ``` You can then inject the `ApiClientInterface` directly into your controllers/services. ``` class VerifyController extends AbtractController { public function __construct( private ApiClientInterface $apiClient, ) { } // ... } ``` You also need to add the custom address denormalizer to the `services.yaml`: ``` Hyra\IeCompaniesRegistrationOfficeLookup\Model\AddressDenormalizer: ~ ``` ### Configuration outside Symfony [](#configuration-outside-symfony) If you're not using Symfony, you'll need to instantiate the API client yourself, which can be registered in your service container or just used directly. We have provided some helpers in the `Dependencies` class in order to create the Symfony Serializer and Validator with minimal options. ``` use Hyra\IeCompaniesRegistrationOfficeLookup\Dependencies; use Hyra\IeCompaniesRegistrationOfficeLookup\ApiClient; $email = '' $apiKey = '' // Whichever http client you choose $httpClient = new HttpClient(); $denormalizer = Dependencies::serializer(); $validator = Dependencies::validator(); $apiClient = new ApiClient($denormalizer, $validator, $httpClient, $apiKey, $email); ``` ### Looking up a business number [](#looking-up-a-business-number) Once you have configured your `ApiClient` you can look up an individual business numbers. Note, this will validate the number before calling the API in order to prevent unnecessary API requests. ``` $number = '9429032389470'; try { $response = $apiClient->lookupNumber($number); } catch (ConnectionException $e) { die($e->getMessage()) } catch (NumberInvalidException) { die('Invalid business number'); } catch (NumberNotFoundException) { die('Business number not found'); } echo $response->companyNumber; // 9429032389470 echo $response->entityName; // BURGER FUEL LIMITED echo $response->status; // Registered ``` Testing ------- [](#testing) In automated tests, you can replace the `ApiClient` with the `StubApiClient` in order to mock responses from the API. There is also the `BusinessNumberFaker` which you can use during tests to get both valid and invalid business numbers. ``` use Hyra\IeCompaniesRegistrationOfficeLookup\Stubs\BusinessNumberFaker; use Hyra\IeCompaniesRegistrationOfficeLookup\Stubs\StubApiClient; use Hyra\IeCompaniesRegistrationOfficeLookup\Stubs\MockBusinessRegistryResponse; $stubClient = new StubApiClient(); $stubClient->lookupNumber(BusinessNumberFaker::invalidBusinessNumber()); // NumberInvalidException - Note, the stub still uses the validator $stubClient->lookupNumber(BusinessNumberFaker::validBusinessNumber()); // LogicException - You need to tell the stub how to respond to specific queries $businessNumber = BusinessNumberFaker::validBusinessNumber(); $stubClient->addNotFoundBusinessNumbers($businessNumber); $stubClient->lookupNumber($businessNumber); // NumberNotFoundException $businessNumber = BusinessNumberFaker::validBusinessNumber(); $mockResponse = MockBusinessRegistryResponse::valid(); $mockResponse->businessNumber = $businessNumber; $stubClient->addMockResponse($mockResponse); $response = $stubClient->lookupNumber($businessNumber); // $response === $mockResponse ``` Contributing ------------ [](#contributing) All contributions are welcome! You'll need [docker](https://docs.docker.com/engine/install/) installed in order to run tests and CI processes locally. These will also be run against your pull request with any failures added as GitHub annotations in the Files view. ``` # First build the required docker container $ docker compose build # Then you can install composer dependencies $ docker compose run php make vendor # Now you can run tests and other tools $ docker compose run php make (fix|psalm|phpstan|phpunit) ``` In order for you PR to be accepted, it will need to be covered by tests and be accepted by: - [php-cs-fixer](https://github.com/FriendsOfPhp/PHP-CS-Fixer) - [psalm](https://github.com/vimeo/psalm/) - [phpstan](https://github.com/phpstan/phpstan) ### Health Score 36 — LowBetter than 82% of packages Maintenance50 Moderate activity, may be stable Popularity26 Limited adoption so far Community10 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 80% 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 ~122 days Total 2 Last Release 357d ago Major Versions v1.0.0-beta.1 → 2.0.02025-05-26 ### Community Maintainers ![](https://www.gravatar.com/avatar/3cfed44ee6ac4e4cec6e652326847c4f71d5acc5bd535c7e6fecde526846a5d9?d=identicon)[procurepro](/maintainers/procurepro) --- Top Contributors [![mijohen](https://avatars.githubusercontent.com/u/5109410?v=4)](https://github.com/mijohen "mijohen (4 commits)")[![cborgas](https://avatars.githubusercontent.com/u/27918855?v=4)](https://github.com/cborgas "cborgas (1 commits)") --- Tags business-numbercompanies-registration-officecroirish-business-numbersdk-php ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Psalm Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/hyraiq-ie-companies-registration-office-lookup/health.svg) ``` [![Health](https://phpackages.com/badges/hyraiq-ie-companies-registration-office-lookup/health.svg)](https://phpackages.com/packages/hyraiq-ie-companies-registration-office-lookup) ``` ### Alternatives [shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[prestashop/prestashop PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers. 9.0k15.4k](/packages/prestashop-prestashop)[symfony/ai-agent PHP library for building agentic applications. 30536.7k44](/packages/symfony-ai-agent)[cognesy/instructor-php The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control 310107.9k1](/packages/cognesy-instructor-php)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core)[symfony/ai-platform PHP library for interacting with AI platform provider. 51927.7k136](/packages/symfony-ai-platform) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)