Merge pull request #3 from JustSteveKing/2.0

2.0
JustSteveKing · May 7, 2021 · bcd4255 · bcd4255
2 parents c647cbe + 02e44d9
commit bcd4255
Show file tree

Hide file tree

Showing 43 changed files with 1,587 additions and 1,142 deletions.
diff --git a/.env.ci b/.env.ci
@@ -0,0 +1,5 @@
+COMPANIES_HOUSE_KEY=123456
+COMPANIES_HOUSE_URL="https://api.company-information.service.gov.uk"
+COMPANIES_HOUSE_TIMEOUT=10
+COMPANIES_HOUSE_RETRY_TIMES=
+COMPANIES_HOUSE_RETRY_MILLISECONDS=
diff --git a/.github/workflows/php-cs-fixer.yml b/.github/workflows/php-cs-fixer.yml
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -9,14 +9,12 @@ jobs:
       fail-fast: true
       matrix:
         os: [ubuntu-latest]
-        php: [7.4]
-        laravel: [7.*, 8.*]
+        php: [8.0]
+        laravel: [8.*]
         dependency-version: [prefer-stable]
         include:
           - laravel: 8.*
             testbench: 6.*
-          - laravel: 7.*
-            testbench: 5.*
 
     name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.dependency-version }} - ${{ matrix.os }}
 

diff --git a/.php_cs.dist b/.php_cs.dist
diff --git a/README.md b/README.md
@@ -1,19 +1,17 @@
+# Laravel Companies House
+
 <p align="center">
 
 ![](./companies-house-laravel.png)
 
 </p>
 
-# A Laravel wrapper to get companies house information and validate company numbers
-
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/juststeveking/companies-house-laravel.svg?style=flat-square)](https://packagist.org/packages/juststeveking/companies-house-laravel)
 ![Tests](https://github.com/juststeveking/companies-house-laravel/workflows/Tests/badge.svg?branch=master)
 [![Total Downloads](https://img.shields.io/packagist/dt/juststeveking/companies-house-laravel.svg?style=flat-square)](https://packagist.org/packages/juststeveking/companies-house-laravel)
 
 
-A Laravel wrapper to get companies house information and validate company numbers. This is a work in progress and more methods will be added to the API as they are required.
-
-This has been tested thoroughly in Laravel 8, Laravel 7 is supported but if you find issues please do drop a detailed issue.
+A Laravel wrapper to get companies house information and validate company numbers.
 
 ## Installation
 
@@ -25,7 +23,7 @@ composer require juststeveking/companies-house-laravel
 
 You can publish the config file with:
 ```bash
-php artisan vendor:publish --provider="JustSteveKing\CompaniesHouseLaravel\CompaniesHouseLaravelServiceProvider" --tag="config"
+php artisan vendor:publish --provider="JustSteveKing\CompaniesHouse\CompaniesHouseServiceProvider" --tag="config"
 ```
 
 This is the contents of the published config file:
@@ -34,86 +32,194 @@ This is the contents of the published config file:
 return [
     'api' => [
         'key' => env('COMPANIES_HOUSE_KEY', ''),
-        'url' => env('COMPANIES_HOUSE_URL', 'https://api.companieshouse.gov.uk')
+        '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
 
-Using it inline:
+This library is aimed to be easy to use, and slots into Laravel with no issues.
 
-```php
-use JustSteveKing\CompaniesHouseLaravel\Client;
+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.
 
-// Make a new client
-$api = Client::make();
 
-// Get Company information from a company number
-$company = $api->company('company-number');
-```
+### Get A Company Profile
 
-Using the validation inline:
+To get a company profile, you can quite simply:
 
 ```php
-$this->validate($request, [
-    'company_number' => [
-        'required',
-        'string',
-        Rule::companyNumber()
-    ]
-]);
+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')
+        );
+    }
+}
 ```
 
-Searching for a company by name, please note this will return an empty collection if there are no results:
+
+## Get A Companies Officers
+
+You can get a `Collection` of Company Officers using the companies number:
 
 ```php
-use JustSteveKing\CompaniesHouseLaravel\Client;
+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')
+        );
+    }
+}
+```
+
 
-$api = Client::make();
+### Get a specific Officer from a Company
 
-// Get a collection of Company\SearchResult inside of a CompanyCollection
-$results = $api->searchCompany('Name you want to search');
+You can get an `Officer` from a company using the company number and their appointment ID:
 
-// You now have access to all standard Laravel collection methods
-$results->each(function ($result) {
-    // Do something with the result here.
-});
+```php
+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'),
+        );
+    }
+}
 ```
 
-Fetching a Collection of Company Officers will return an OfficerCollection:
 
-```php
-use JustSteveKing\CompaniesHouseLaravel\Client;
+### Searching
+
+There are a few options when it comes to searching, you can search for:
+
+- companies
+- officers
+- disqualified officers
+- search all
+
 
-$api = Client::make();
+#### Searching for Companies
 
-// Get a collection of Company\SearchResult inside of a CompanyCollection
-$results = $api->getOfficers('company-number');
+This will return a `SearchCollection`
 
-// You now have access to all standard Laravel collection methods
-$results->each(function ($result) {
-    // Do something with the result here.
-});
+```php
+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
+        );
+    }
+}
 ```
 
 
-## Testing
+#### Searching for Officers
+
+This will return a `SearchCollection`
+
+```php
+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
+        );
+    }
+}
+```
 
-### Using this library in your own tests
 
-There is a relatively simple testing utility on this library, that allows you to fake the underlying Http client:
+#### Searching everything
+
+This will return a `SearchCollection`
 
 ```php
-use Illuminate\Support\Facades\Http
-use JustSteveKing\CompaniesHouseLaravel\Client;
+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:
 
-$fakedApi = Client::fake([
-    'https://api.companieshouse.gov.uk/*',
-    Http::response([], 200, [])
+```php
+$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](https://laravel.com/docs/8.x/http-client#testing)