PHPackages hyraiq/nz-companies-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. [Validation & Sanitization](/categories/validation) 4. / 5. hyraiq/nz-companies-office-lookup ActiveLibrary[Validation & Sanitization](/categories/validation) hyraiq/nz-companies-office-lookup ================================= NZ business number validation and verification using the NZ Companies Office web services API 2.0.0(12mo ago)1123.3k—0%MITPHPPHP >=8.2CI passing Since Apr 27Pushed 12mo ago1 watchersCompare [ Source](https://github.com/hyraiq/nz-companies-office-lookup)[ Packagist](https://packagist.org/packages/hyraiq/nz-companies-office-lookup)[ RSS](/packages/hyraiq-nz-companies-office-lookup/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (7)Dependencies (21)Versions (10)Used By (0) hyraiq/nz-companies-office-lookup ================================= [](#hyraiqnz-companies-office-lookup) A PHP SDK to validate NZ Business Number (NZBNs) and verify them with the [NZ Companies Office Public Data API](https://portal.api.business.govt.nz/api-details#api=nzbn). 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 NZBN. This *does not* contact the API to ensure that the given ABN is assigned to a business - Verification contacts the Companies Office through their API to retrieve information registered against the ABN. It will tell you if the ABN actually belongs to a business. In order to use the API (only necessary for verification), you'll need to [register an account](https://support.api.business.govt.nz/s/article/cloud-subscriptions) 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 [NzCompanyResponse](./src/Model/NzCompanyResponse.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 ABN is invalid (i.e. validation failed) - `NumberNotFoundException.php`: The ABN is valid, however it is not assigned to a business (i.e. verification failed) Usage ----- [](#usage) ### Installation [](#installation) ``` $ composer require hyraiq/nz-companies-office-lookup ``` ### Configuration with Symfony [](#configuration-with-symfony) In `services.yaml`, you need to pass you ABR API key to the `ApiClient` and register the `ApiClient` with the `ApiClientInterface`: ``` Hyra\NzCompaniesHouseLookup\ApiClientInterface: '@Hyra\NzCompaniesHouseLookup\ApiClient' Hyra\NzCompaniesHouseLookup\ApiClient: arguments: $apiKey: "%env(NZ_COMPANIES_OFFICE_API_KEY)%" ``` 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\NzCompaniesOfficeLookup\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\NzCompaniesHouseLookup\Dependencies; use Hyra\NzCompaniesHouseLookup\ApiClient; $apiKey = '' // Whichever http client you choose $httpClient = new HttpClient(); $denormalizer = Dependencies::serializer(); $validator = Dependencies::validator(); $apiClient = new ApiClient($denormalizer, $validator, $httpClient, $apiKey); ``` ### Looking up a business number [](#looking-up-a-business-number) Once you have configured your `ApiClient` you can look up an individual ABN. Note, this will validate the ABN 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 NZBNs. ``` use Hyra\NzCompaniesOfficeLookup\Stubs\BusinessNumberFaker; use Hyra\NzCompaniesOfficeLookup\Stubs\StubApiClient; use Hyra\NzCompaniesOfficeLookup\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 42 — FairBetter than 90% of packages Maintenance50 Moderate activity, may be stable Popularity31 Limited adoption so far Community10 Small or concentrated contributor base Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 85.7% 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 ~94 days Recently: every ~182 days Total 9 Last Release 361d ago Major Versions v1.3.2 → 2.0.02025-05-23 PHP version history (3 changes)v1.0.0-beta.1PHP >=8.0 v1.2.0PHP >=8.1 2.0.0PHP >=8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/3cfed44ee6ac4e4cec6e652326847c4f71d5acc5bd535c7e6fecde526846a5d9?d=identicon)[procurepro](/maintainers/procurepro) --- Top Contributors [![kielabokkie](https://avatars.githubusercontent.com/u/1221750?v=4)](https://github.com/kielabokkie "kielabokkie (12 commits)")[![cborgas](https://avatars.githubusercontent.com/u/27918855?v=4)](https://github.com/cborgas "cborgas (1 commits)")[![ndench](https://avatars.githubusercontent.com/u/2062388?v=4)](https://github.com/ndench "ndench (1 commits)") --- Tags business-numbercompanies-officenz-business-numbernz-companies-officesdk-php ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Psalm Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/hyraiq-nz-companies-office-lookup/health.svg) ``` [![Health](https://phpackages.com/badges/hyraiq-nz-companies-office-lookup/health.svg)](https://phpackages.com/packages/hyraiq-nz-companies-office-lookup) ``` ### Alternatives [shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M651](/packages/sylius-sylius)[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)[sulu/sulu Core framework that implements the functionality of the Sulu content management system 1.3k1.3M152](/packages/sulu-sulu)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core)[web-auth/webauthn-framework FIDO2/Webauthn library for PHP and Symfony Bundle. 50570.7k1](/packages/web-auth-webauthn-framework) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)