Download the PHP package hyraiq/uk-companies-house-lookup without Composer

hyraiq/uk-companies-house-lookup

A PHP SDK to validate UK Company Registration Number (CRNs) and verify them with the UK Companies House Public Data API. 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 CRN. This does not contact the API to ensure that the given CRN is assigned to a business
• Verification contacts the Companies House through their API to retrieve information registered against the CRN. It will tell you if the CRN actually belongs to a business.

In order to use the API (only necessary for verification), you'll need to register an account to receive an API key.

Type safety

The SDK utilises the Symfony Serializer and the Symfony Validator to deserialize and validate data returned from the API in order to provide a valid CompanyResponse 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 CRN is invalid (i.e. validation failed)
• NumberNotFoundException.php: The CRN is valid, however it is not assigned to a business (i.e. verification failed)

Usage

Installation

Configuration with Symfony

In services.yaml, you need to pass you ABR API key to the ApiClient and register the ApiClient with the ApiClientInterface:

You can then inject the ApiClientInterface directly into your controllers/services.

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.

Looking up a business number

Once you have configured your ApiClient you can look up an individual CRN. Note, this will validate the CRN before calling the API in order to prevent unnecessary API requests.

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 CRNs.

Contributing

All contributions are welcome! You'll need docker 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.

In order for you PR to be accepted, it will need to be covered by tests and be accepted by:

• php-cs-fixer
• psalm
• phpstan