feat: parser now writes, added missing fields

updated docs, example, extensive use of Traits with better handling.
valid level 9 phpstan codebase.

src/BusinessDataFetcher.php

@@ -6,6 +6,7 @@ use GuzzleHttp\Client;
 use GuzzleHttp\Exception\RequestException;
 use Ivuorinen\BusinessDataFetcher\Dto\BisCompanyDetails;
 use Ivuorinen\BusinessDataFetcher\Exceptions\ApiResponseErrorException;
+use Psr\Http\Message\ResponseInterface;
 
 /**
  * Fetches and returns business data from avoindata
@@ -31,16 +32,13 @@ class BusinessDataFetcher
     /**
      * Fetch Business Information.
      *
-     * @param string $businessId
-     *
-     * @return array $response_data
+     * @return BisCompanyDetails[] $response_data
      * @throws \Exception|\GuzzleHttp\Exception\GuzzleException
      */
     public function getBusinessInformation(string $businessId): array
     {
         // Set request variables
         $requestUrl    = '/bis/v1';
-        $response_data = [];
 
         // Get the business data
         try {
@@ -54,7 +52,7 @@ class BusinessDataFetcher
                 );
             }
 
-            $response_data = $this->parse_response($response);
+            $response_data = $this->parseResponse($response);
         } catch (RequestException $exception) {
             throw new ApiResponseErrorException(
                 $exception->getMessage(),
@@ -67,13 +65,14 @@ class BusinessDataFetcher
     }
 
     /**
-     * @param \Psr\Http\Message\ResponseInterface $response
+     * Parse the response from the API.
      *
-     * @return array
+     * @return BisCompanyDetails[]
      * @throws \JsonException
      * @throws \Spatie\DataTransferObject\Exceptions\UnknownProperties
+     * @throws \Ivuorinen\BusinessDataFetcher\Exceptions\ApiResponseErrorException
      */
-    public function parse_response(\Psr\Http\Message\ResponseInterface $response): array
+    public function parseResponse(ResponseInterface $response): array
     {
         $data = json_decode(
             $response->getBody()->getContents(),
@@ -82,6 +81,20 @@ class BusinessDataFetcher
             JSON_THROW_ON_ERROR
         );
 
+        if (!is_array($data)) {
+            throw new ApiResponseErrorException(
+                'Invalid response data',
+                $response->getStatusCode()
+            );
+        }
+
+        if (!isset($data['results'])) {
+            throw new ApiResponseErrorException(
+                'Invalid response data',
+                $response->getStatusCode()
+            );
+        }
+
         $results = [];
 
         foreach ($data['results'] as $result) {

src/Dto/BisAddress.php

@@ -2,25 +2,22 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
- * Business Address
+ * Address
  */
 class BisAddress extends DataTransferObject
 {
-    use HasSource;
-
-    /**
-     * One for current version and >1 for historical addresses
-     */
-    public int $version;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
@@ -47,11 +44,6 @@ class BisAddress extends DataTransferObject
      */
     public ?string $city = null;
 
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
-
     /**
      * Type of address, 1 for street address, 2 for postal address
      */

src/Dto/BisCompanyBusinessIdChange.php

@@ -2,61 +2,40 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
- * Company Business ID Change
+ * Company Business Id Change
  */
 class BisCompanyBusinessIdChange extends DataTransferObject
 {
-    use HasSource;
+    use Traits\HasSource;
+    use Traits\HasLanguage;
+    use Traits\HasChange;
 
     /**
      * Description of reason
      */
-    public string $description = "";
+    public string $description = '';
 
     /**
      * Reason code
      */
-    public string $reason = "";
+    public string $reason = '';
 
     /**
      * Date of Business ID change
      */
     public ?string $changeDate = null;
 
-    /**
-     * Business ID Change
-     *
-     * 2 = Business ID removal,
-     * 3 = Combining of double IDs,
-     * 5 = ID changed,
-     * 44 = Fusion,
-     * 45 = Operator continuing VAT activities,
-     * 46 = Relation to predecessor,
-     * 47 = Division,
-     * 48 = Bankruptcy relationship,
-     * 49 = Operations continued by a private trader,
-     * 57 = Partial division,
-     * DIF = Division,
-     * FUU = Fusion
-     */
-    public int $change;
-
     /**
      * Old Business ID
      */
-    public string $oldBusinessId = "";
+    public string $oldBusinessId = '';
 
     /**
      * New Business ID
      */
-    public string $newBusinessId = "";
-
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
+    public string $newBusinessId = '';
 }

src/Dto/BisCompanyBusinessLine.php

@@ -2,30 +2,27 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Business Line
  */
 class BisCompanyBusinessLine extends DataTransferObject
 {
-    use HasSource;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
      * Zero for main line of business, positive for others
      */
     public int $order;
 
-    /**
-     * One for current version and >1 for historical lines of business
-     */
-    public int $version;
-
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
@@ -35,10 +32,5 @@ class BisCompanyBusinessLine extends DataTransferObject
     /**
      * Name of line of business
      */
-    public string $name = "";
-
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
+    public string $name = '';
 }

src/Dto/BisCompanyContactDetail.php

@@ -2,43 +2,35 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Contact Detail
  */
 class BisCompanyContactDetail extends DataTransferObject
 {
-    use HasSource;
-
-    /**
-     * One for current version and >1 for historical contact details
-     */
-    public int $version;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
      */
     public ?string $endDate = null;
 
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
-
     /**
      * Value of contact detail
      */
-    public string $value = "";
+    public string $value = '';
 
     /**
      * Type of contact detail
      */
-    public string $type = "";
+    public string $type = '';
 }

src/Dto/BisCompanyDetails.php

@@ -2,9 +2,9 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
+use Spatie\DataTransferObject\DataTransferObject;
 use Spatie\DataTransferObject\Attributes\CastWith;
 use Spatie\DataTransferObject\Casters;
-use Spatie\DataTransferObject\DataTransferObject;
 
 /**
  * Company Details
@@ -91,12 +91,12 @@ class BisCompanyDetails extends DataTransferObject
     /**
      * Business ID
      */
-    public string $businessId = "";
+    public string $businessId = '';
 
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Company form
@@ -111,5 +111,5 @@ class BisCompanyDetails extends DataTransferObject
     /**
      * Primary company name
      */
-    public string $name = "";
+    public string $name = '';
 }

src/Dto/BisCompanyForm.php

@@ -2,25 +2,22 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Form
  */
 class BisCompanyForm extends DataTransferObject
 {
-    use HasSource;
-
-    /**
-     * One for current version and >1 for historical company forms
-     */
-    public int $version;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
@@ -30,20 +27,10 @@ class BisCompanyForm extends DataTransferObject
     /**
      * Name of company form
      */
-    public string $name = "";
+    public string $name = '';
 
     /**
-     * Two letter language code
+     * Type of company form
      */
-    public ?string $language = null;
-
-    /**
-     * Type of company form.
-     *
-     * Note: According to spec, this shouldn't be nullable,
-     * but payloads show otherwise.
-     *
-     * @var string|null
-     */
-    public ?string $type;
+    public string $type = '';
 }

src/Dto/BisCompanyLanguage.php

@@ -2,25 +2,22 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Language
  */
 class BisCompanyLanguage extends DataTransferObject
 {
-    use HasSource;
-
-    /**
-     * One for current version and >1 for historical company forms
-     */
-    public int $version;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
@@ -28,17 +25,7 @@ class BisCompanyLanguage extends DataTransferObject
     public ?string $endDate = null;
 
     /**
-     * Bankruptcy, liquidation or restructuring proceedings
+     * Name of language
      */
-    public string $name = "";
-
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
-
-    /**
-     * Type of liquidation
-     */
-    public string $type = "";
+    public string $name = '';
 }

src/Dto/BisCompanyLiquidation.php

@@ -2,25 +2,22 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Liquidation
  */
 class BisCompanyLiquidation extends DataTransferObject
 {
-    use HasSource;
-
-    /**
-     * One for current version and >1 for historical company forms
-     */
-    public int $version;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
@@ -30,15 +27,10 @@ class BisCompanyLiquidation extends DataTransferObject
     /**
      * Bankruptcy, liquidation or restructuring proceedings
      */
-    public string $name = "";
-
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
+    public string $name = '';
 
     /**
      * Type of liquidation
      */
-    public string $type = "";
+    public string $type = '';
 }

src/Dto/BisCompanyName.php

@@ -2,33 +2,27 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Name
  */
 class BisCompanyName extends DataTransferObject
 {
-    use HasSource;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
-     * Order
-     *
-     * Zero for primary company name,
-     * other for translations of the primary company name
-     * and auxiliary company names
+     * Zero for primary company name, other for translations of the primary company name and auxiliary company names
      */
     public int $order;
-    /**
-     * One for current version and >1 for historical company names
-     */
-    public int $version;
 
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
@@ -38,10 +32,5 @@ class BisCompanyName extends DataTransferObject
     /**
      * Company name
      */
-    public string $name = "";
-
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
+    public string $name = '';
 }

src/Dto/BisCompanyRegisteredEntry.php

@@ -2,18 +2,22 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Exceptions\UnexpectedValueException;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Registered Entry
  */
 class BisCompanyRegisteredEntry extends DataTransferObject
 {
+    use Traits\HasAuthority;
+    use Traits\HasLanguage;
+    use Traits\HasRegister;
+
     /**
      * Description of entry
      */
-    public string $description = "";
+    public string $description = '';
 
     /**
      * Zero for common entries, one for ‘Unregistered’ and two for ‘Registered’
@@ -23,76 +27,10 @@ class BisCompanyRegisteredEntry extends DataTransferObject
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
      */
     public ?string $endDate = null;
-
-    /**
-     * register (int):
-     * - One for Trade Register,
-     * - two for Register of Foundations,
-     * - three for Register of Associations,
-     * - four for Tax Administration,
-     * - five for Prepayment Register,
-     * - six for VAT Register,
-     * - seven for Employer Register and
-     * - eight for register of bodies liable for tax on insurance premiums
-     *
-     * @see getRegisterText()
-     */
-    public int $register;
-    /**
-     * Two letter language code
-     */
-    public ?string $language;
-    /**
-     * authority (int):
-     * - One for Tax Administration,
-     * - two for Finnish Patent and Registration Office and
-     * - three for Population Register
-     *
-     * @see getAuthorityText()
-     *
-     * @var int
-     */
-    public int $authority;
-
-    public function getStatusText(): string
-    {
-        //  Zero for common entries, one for ‘Unregistered’ and two for ‘Registered’
-        return match ($this->status) {
-            0 => "Common",
-            1 => "Unregistered",
-            2 => "Registered",
-            default => throw new UnexpectedValueException("Unexpected value: " . $this->status),
-        };
-    }
-
-    public function getRegisterText(): string
-    {
-        return match ($this->register) {
-            1 => "Trade Register",
-            2 => "Register of Foundations",
-            3 => "Register of Associations",
-            4 => "Tax Administration",
-            5 => "Prepayment Register",
-            6 => "VAT Register",
-            7 => "Employer Register",
-            8 => "register of bodies liable for tax on insurance premiums",
-            default => throw new UnexpectedValueException("Unexpected value: " . $this->register),
-        };
-    }
-
-    public function getAuthorityText(): string
-    {
-        return match ($this->authority) {
-            1 => "Tax Administration",
-            2 => "Finnish Patent and Registration Office",
-            3 => "Population Register",
-            default => throw new UnexpectedValueException("Unexpected value: " . $this->authority),
-        };
-    }
 }

src/Dto/BisCompanyRegisteredOffice.php

@@ -2,30 +2,27 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Dto;
 
-use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
 use Spatie\DataTransferObject\DataTransferObject;
+use Ivuorinen\BusinessDataFetcher\Traits;
 
 /**
  * Company Registered Office
  */
 class BisCompanyRegisteredOffice extends DataTransferObject
 {
-    use HasSource;
+    use Traits\HasSource;
+    use Traits\HasVersion;
+    use Traits\HasLanguage;
 
     /**
      * Zero for primary place of registered office, positive for others
      */
     public int $order;
 
-    /**
-     * One for current version and >1 for historical places of registered office
-     */
-    public int $version;
-
     /**
      * Date of registration
      */
-    public string $registrationDate = "";
+    public string $registrationDate = '';
 
     /**
      * Ending date of registration
@@ -35,10 +32,5 @@ class BisCompanyRegisteredOffice extends DataTransferObject
     /**
      * Name of place of registered office
      */
-    public string $name = "";
-
-    /**
-     * Two letter language code
-     */
-    public ?string $language = null;
+    public string $name = '';
 }

src/Exceptions/ApiResponseErrorException.php

@@ -2,6 +2,8 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Exceptions;
 
-class ApiResponseErrorException extends \Exception
+use Exception;
+
+class ApiResponseErrorException extends Exception
 {
 }

src/Exceptions/UnexpectedValueException.php

@@ -2,6 +2,8 @@
 
 namespace Ivuorinen\BusinessDataFetcher\Exceptions;
 
-class UnexpectedValueException extends \Exception
+use Exception;
+
+class UnexpectedValueException extends Exception
 {
 }

src/Traits/HasAuthority.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Traits;
+
+trait HasAuthority
+{
+    /**
+     * @see getChangeString()
+     * @var int $authority What authority the change is related to.
+     */
+    public int $authority;
+
+    /**
+     * Get the name of the authority.
+     */
+    public function getAuthorityString(): string
+    {
+        return match ($this->authority) {
+            1 => 'Tax Administration',
+            2 => 'Finnish Patent and Registration Office',
+            3 => 'Population Register',
+            default => 'unknown:' . $this->authority,
+        };
+    }
+}

src/Traits/HasChange.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Traits;
+
+trait HasChange
+{
+    /**
+     * @see getChangeString()
+     * @var string|int|null $change Change as a string or integer.
+     *                              Models claim this is an integer, but it can also be a string.
+     */
+    public string|int|null $change;
+
+    /**
+     * Get the description string of the change.
+     */
+    public function getChangeString(): string
+    {
+        return match ($this->change) {
+            2 => 'Business ID removal',
+            3 => 'Combining of double IDs',
+            5 => 'ID changed',
+            44, 'FUU' => 'Fusion',
+            45 => 'Operator continuing VAT activities',
+            46 => 'Relation to predecessor',
+            47, 'DIF' => 'Division',
+            48 => 'Bankruptcy relationship',
+            49 => 'Operations continued by a private trader',
+            57 => 'Partial division',
+            default => 'unknown:' . $this->change,
+        };
+    }
+}

src/Traits/HasLanguage.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Traits;
+
+trait HasLanguage
+{
+    /**
+     * @see getLanguageString()
+     * @var string|null $language Two letter language code
+     *                            (e.g. 'fi', 'sv', 'en')
+     */
+    public ?string $language;
+
+    /**
+     * Get the language code as a string.
+     */
+    public function getLanguageString(): string
+    {
+        return match ($this->language) {
+            'fi' => 'finnish',
+            'en' => 'english',
+            'sv' => 'swedish',
+            default => 'unknown:' . $this->language,
+        };
+    }
+}

src/Traits/HasRegister.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Traits;
+
+trait HasRegister
+{
+    /**
+     * @see getRegisterString()
+     * @var int|null $register What register the change is related to.
+     */
+    public int|null $register;
+
+    /**
+     * Get the name of the register.
+     */
+    public function getRegisterString(): string
+    {
+        return match ($this->register) {
+            1 => 'Trade Register',
+            2 => 'Register of Foundations',
+            3 => 'Register of Associations',
+            4 => 'Tax Administration',
+            5 => 'Prepayment Register',
+            6 => 'VAT Register',
+            7 => 'Employer Register',
+            8 => 'Register of bodies liable for tax on insurance premiums',
+            default => 'unknown:' . $this->register,
+        };
+    }
+}

src/Traits/HasVersion.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Traits;
+
+trait HasVersion
+{
+    /**
+     * One for current version and >1 for historical contact details.
+     */
+    public int $version = 0;
+}