juststeveking/companies-house-laravel

A Laravel wrapper to get companies house information and validate company numbers

2.0.4 2021-09-14 09:47 UTC

Requires

• php: ^8.0
• illuminate/contracts: ^8.40
• illuminate/support: ^8.0
• spatie/data-transfer-object: ^3.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.16
• guzzlehttp/guzzle: ^7.3
• orchestra/testbench: ^6.0
• phpunit/phpunit: ^9.3
• vimeo/psalm: ^3.11

MIT

• Steve McDougall

• api
• validation
• integration
• companies house
• JustSteveKing
• companies-house-laravel

README

A Laravel wrapper to get companies house information and validate company numbers.

Installation

You can install the package via composer:

composer require juststeveking/companies-house-laravel

You can publish the config file with:

php artisan vendor:publish --provider="JustSteveKing\CompaniesHouse\CompaniesHouseServiceProvider" --tag="config"

This is the contents of the published config file:

return [
    'api' => [
        'key' => env('COMPANIES_HOUSE_KEY', ''),
        'url' => env('COMPANIES_HOUSE_URL', 'https://api.company-information.service.gov.uk'),
        'timeout' => env('COMPANIES_HOUSE_TIMEOUT', 10),
        'retry' => [
            'times' => env('COMPANIES_HOUSE_RETRY_TIMES', null),
            'milliseconds' => env('COMPANIES_HOUSE_RETRY_MILLISECONDS', null),
        ],
    ]
];

Usage

This library is aimed to be easy to use, and slots into Laravel with no issues.

The package will install a Service Provider for you, meaning that all you need to do is resolve the Client from the container, and start using it.

Get A Company Profile

To get a company profile, you can quite simply:

use JustSteveKing\CompaniesHouse\Client;

class CompanyController extends Controler
{
    public function __construct(
        protected Client $service,
    ) {}

    public function __invoke(Request $request)
    {
        $company = $this->service->company(
            companyNumber: $request->get('company_number')
        );
    }
}

Get A Companies Officers

You can get a Collection of Company Officers using the companies number:

use JustSteveKing\CompaniesHouse\Client;

class CompanyOfficersController extends Controler
{
    public function __construct(
        protected Client $service,
    ) {}

    public function __invoke(Request $request)
    {
        $company = $this->service->officers(
            companyNumber: $request->get('company_number')
        );
    }
}

Get a specific Officer from a Company

You can get an Officer from a company using the company number and their appointment ID:

use JustSteveKing\CompaniesHouse\Client;

class CompanyOfficerController extends Controler
{
    public function __construct(
        protected Client $service,
    ) {}

    public function __invoke(Request $request)
    {
        $company = $this->service->officer(
            companyNumber: $request->get('company_number'),
            appointmentId: $request->get('appointment_id'),
        );
    }
}

Searching

There are a few options when it comes to searching, you can search for:

• companies
• officers
• disqualified officers
• search all

Searching for Companies

This will return a SearchCollection

use JustSteveKing\CompaniesHouse\Client;

class CompanySearchController extends Controler
{
    public function __construct(
        protected Client $service,
    ) {}

    public function __invoke(Request $request)
    {
        $results = $this->service->searchCompany(
            query: $request->get('query'),
            perPage: 25, //optional
            startIndex: 0, //optional
        );
    }
}

Searching for Officers

This will return a SearchCollection

use JustSteveKing\CompaniesHouse\Client;

class OfficersSearchController extends Controler
{
    public function __construct(
        protected Client $service,
    ) {}

    public function __invoke(Request $request)
    {
        $results = $this->service->searchOfficers(
            query: $request->get('query'),
            perPage: 25, //optional
            startIndex: 0, //optional
        );
    }
}

Searching everything

This will return a SearchCollection

use JustSteveKing\CompaniesHouse\Client;

class SearchController extends Controler
{
    public function __construct(
        protected Client $service,
    ) {}

    public function __invoke(Request $request)
    {
        $results = $this->service->search(
            query: $request->get('query'),
            perPage: 25, //optional
            startIndex: 0, //optional
        );
    }
}

Validation

Using the validation inline:

$this->validate($request, [
    'company_number' => [
        'required',
        'string',
        Rule::companyNumber()
    ]
]);

Testing

To understand how to use this part please follow the Laravel documentation for Testing the Http Client

Run the unit tests:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Steve McDougall
• All Contributors

License

The MIT License (MIT). Please see License File for more information.