chore(docs): uses PRH BIS API v1

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

.github/workflows/composer.yml

@@ -1,3 +1,4 @@
+---
 name: PHP Composer
 
 on:
@@ -12,11 +13,20 @@ permissions:
 jobs:
   build:
 
-    runs-on: ubuntu-latest
+    # pre-installed php from 7.4 to 8.3
+    runs-on: ubuntu-22.04
+
+    strategy:
+      matrix:
+        php-versions: ['8.2', '8.3']
 
     steps:
     - uses: actions/checkout@v4
 
+    - uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ matrix.php-versions }}
+
     - name: Validate composer.json and composer.lock
       run: composer validate --strict
 
@@ -25,8 +35,9 @@ jobs:
       uses: actions/cache@v4
       with:
         path: vendor
-        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+        key: ${{ runner.os }}-php-${{ matrix.php-versions }}-${{ hashFiles('**/composer.lock') }}
         restore-keys: |
+          ${{ runner.os }}-php-${{ matrix.php-versions }}-
           ${{ runner.os }}-php-
 
     - name: Install dependencies

README.md

@@ -1,7 +1,7 @@
 # Business Data Fetcher
 
 This is an API client to Finnish Patent and Registration
-Office's (PRH) Business Information System (BIS).
+Office's (PRH) Business Information System (BIS) v1.
 
 Use it to get company data from the Business Information System by Business ID.
 

composer.json

@@ -5,7 +5,7 @@
     "license": "MIT",
     "require": {
         "php": "^8.2",
-        "guzzlehttp/guzzle": "^7.4.5",
+        "guzzlehttp/guzzle": "^7.4",
         "spatie/data-transfer-object": "^3.9"
     },
     "autoload": {
@@ -15,6 +15,13 @@
     },
     "require-dev": {
         "squizlabs/php_codesniffer": "^3.10",
-        "ivuorinen/markdowndocs": "^4.0"
+        "ivuorinen/markdowndocs": "^4.0",
+        "phpstan/phpstan": "^1.11"
+    },
+    "scripts": {
+        "docs": "php vendor/bin/phpdoc-md generate src > docs.md",
+        "lint": "php vendor/bin/phpcs --standard=PSR12 src",
+        "lint-fix": "php vendor/bin/phpcbf --standard=PSR12 src",
+        "phpstan": "php vendor/bin/phpstan analyse"
     }
 }

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "7364c4b7d7bc5996960ea3dafcba82ef",
+    "content-hash": "03248eb4886355e9781bcffce2553099",
     "packages": [
         {
             "name": "guzzlehttp/guzzle",
@@ -731,6 +731,64 @@
             },
             "time": "2024-08-15T01:08:58+00:00"
         },
+        {
+            "name": "phpstan/phpstan",
+            "version": "1.11.10",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/phpstan/phpstan.git",
+                "reference": "640410b32995914bde3eed26fa89552f9c2c082f"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/640410b32995914bde3eed26fa89552f9c2c082f",
+                "reference": "640410b32995914bde3eed26fa89552f9c2c082f",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^7.2|^8.0"
+            },
+            "conflict": {
+                "phpstan/phpstan-shim": "*"
+            },
+            "bin": [
+                "phpstan",
+                "phpstan.phar"
+            ],
+            "type": "library",
+            "autoload": {
+                "files": [
+                    "bootstrap.php"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "description": "PHPStan - PHP Static Analysis Tool",
+            "keywords": [
+                "dev",
+                "static analysis"
+            ],
+            "support": {
+                "docs": "https://phpstan.org/user-guide/getting-started",
+                "forum": "https://github.com/phpstan/phpstan/discussions",
+                "issues": "https://github.com/phpstan/phpstan/issues",
+                "security": "https://github.com/phpstan/phpstan/security/policy",
+                "source": "https://github.com/phpstan/phpstan-src"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/ondrejmirtes",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/phpstan",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-08-08T09:02:50+00:00"
+        },
         {
             "name": "psr/container",
             "version": "2.0.2",

docs.md

@@ -25,7 +25,7 @@
 |:-----------|:---------|
 | public | <strong>__construct()</strong> : <em>void</em><br /><em>BusinessDataFetcher constructor.</em> |
 | public | <strong>getBusinessInformation(</strong><em>\string</em> <strong>$businessId</strong>)</strong> : <em>array</em><br /><em>Fetch Business Information.</em> |
-| public | <strong>parse_response(</strong><em>\Psr\Http\Message\ResponseInterface</em> <strong>$response</strong>)</strong> : <em>array</em> |
+| public | <strong>parseResponse(</strong><em>\Psr\Http\Message\ResponseInterface</em> <strong>$response</strong>)</strong> : <em>array</em><br /><em>Parse the response from the API.</em> |
 
 
 <hr /><a id="class-ivuorinenbusinessdatafetcherdtobiscompanyname"></a>
@@ -36,6 +36,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -49,6 +50,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -58,10 +60,12 @@
 
 ### Class: \Ivuorinen\BusinessDataFetcher\Dto\BisCompanyBusinessIdChange
 
-> Company Business ID Change
+> Company Business Id Change
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getChangeString()</strong> : <em>string</em><br /><em>Get the description string of the change.</em> |
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -71,10 +75,11 @@
 
 ### Class: \Ivuorinen\BusinessDataFetcher\Dto\BisAddress
 
-> Business Address
+> Address
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -88,6 +93,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -101,6 +107,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -114,9 +121,9 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>getAuthorityText()</strong> : <em>string</em> |
-| public | <strong>getRegisterText()</strong> : <em>string</em> |
-| public | <strong>getStatusText()</strong> : <em>string</em> |
+| public | <strong>getAuthorityString()</strong> : <em>string</em><br /><em>Get the name of the authority.</em> |
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
+| public | <strong>getRegisterString()</strong> : <em>string</em><br /><em>Get the name of the register.</em> |
 
 
 *This class extends \Spatie\DataTransferObject\DataTransferObject*
@@ -129,6 +136,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -142,6 +150,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 
@@ -167,6 +176,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
+| public | <strong>getLanguageString()</strong> : <em>string</em><br /><em>Get the language code as a string.</em> |
 | public | <strong>getSourceText()</strong> : <em>string</em> |
 
 

example.php

@@ -6,6 +6,6 @@ $client = new Ivuorinen\BusinessDataFetcher\BusinessDataFetcher();
 try {
     $results = $client->getBusinessInformation("1639413-9");
     print_r($results);
-} catch (\GuzzleHttp\Exception\GuzzleException $e) {
+} catch (Exception $e) {
     var_dump($e);
 }

gen/parser.php

@@ -1,42 +1,53 @@
 <?php
 
-// Load models.txt that contains https://avoindata.prh.fi/ytj_en.html models.
-// Just copy and paste the plaintext Response Class contents to the file and
+// Previously https://avoindata.prh.fi/ytj_en.html had model definitions as plain text.
+// Now the page is not available anymore, but keeping the parser for future use.
+// The models.txt file is a copy of the models from that page.
+// This parser reads the models.txt file and generates DTO classes for the models in the src/Dto directory.
+//
+// Current version of the API by PRH is Swagger based, so the models are available in the Swagger definition:
+// https://avoindata.prh.fi/fi/ytj/swagger-ui
+//
 // run this file: php parser.php
-$models = file_get_contents(sprintf('%s%2$smodels.txt', __DIR__, DIRECTORY_SEPARATOR));
 
-// Capture the names as one group,
-// and blocks inside curly braces as another,
+// Set the directory separator alias.
+const DS = DIRECTORY_SEPARATOR;
+
+// Load the models.txt file.
+$models = file_get_contents(sprintf('%s%smodels.txt', __DIR__, DS));
+
+// Capture the names as one group, and blocks inside curly braces as another,
 // then combine them later.
 preg_match_all("/(\w+)\s\{([\w\W]*?)\}/m", $models, $output_array);
 
 [$all, $names, $fields] = $output_array;
 
-$fields = array_map(function ($f) {
-    $f = explode("\n", $f);
-    $f = array_map("trim", $f);
-    $f = array_filter($f);
+$fields = array_map(static function ($f) {
+    $d = explode("\n", $f);
+    $d = array_map("trim", $d);
+    $d = array_filter($d);
 
-    $f = array_map(function ($field) {
+    $d = array_map(static function ($field) {
         [$name_and_type, $docs] = explode(":", $field, 2);
-        $names_and_types = explode(" ", $name_and_type, 2);
-
-        [$name, $type] = $names_and_types;
+        [$name, $type] = explode(" ", $name_and_type, 2);
 
         $type = str_replace(["(", ")"], "", $type);
 
+        // Handle optional types.
         if (str_contains($type, "optional")) {
             $type = str_replace(["optional", ","], "", $type);
             $type = "?" . trim($type);
         }
 
+        // Handle integer types.
         if ($type === "integer") {
             $type = "int";
         }
 
+        // Handle array types. Convert Array[Type] to Type[].
         if (str_contains($type, "Array")) {
             $type = str_replace(["Array[", "]"], "", $type);
-            $type = $type . "[]";
+            $type .= "[]";
         }
 
         $default = null;
@@ -60,62 +71,90 @@ $fields = array_map(function ($f) {
                 "default" => $default,
             ],
         ];
-    }, $f ?? []);
+    }, $d);
 
-    $f = array_merge(...$f);
-
-    return $f;
+    return array_merge(...$d);
 }, $fields);
 
 $classes = array_combine($names, $fields);
 
 ksort($classes);
 
-// print_r($classes);
+$files = [];
 
-// Files that have already been processed.
-// Uncomment to display the results again.
-$added = [
-    // "BisCompanyRegisteredOffice",
-    // "BisCompanyRegisteredEntry",
-    // "BisCompanyName",
-    // "BisCompanyLiquidation",
-    // "BisCompanyLanguage",
-    // "BisCompanyForm",
-    // "BisCompanyDetails",
-    // "BisCompanyContactDetail",
-    // "BisCompanyBusinessLine",
-    // "BisCompanyBusinessIdChange",
-    // "BisAddress",
-];
-
-// Output the classes as preformatted for easier copypasta.
 // This is not the prettiest way to generate the codes, but it works.
 foreach ($classes as $className => $vars) {
-    if (in_array($className, $added)) {
-        continue;
+    // Get name of the class from filename and split CamelCase to words.
+    $classNameString = $className;
+    $classNameString = str_replace("Bis", "", $classNameString);
+    $classNameString = preg_replace('/(?<!^)[A-Z]/', ' $0', $classNameString);
+    $classNameString = ucwords($classNameString);
+
+    $usesHeader = [
+        "",
+        "use Spatie\DataTransferObject\DataTransferObject;",
+    ];
+
+    $hasCasters = [
+        "BisCompanyDetails",
+    ];
+
+    if (in_array($className, $hasCasters, true)) {
+        $usesHeader["CastWith"] = "use Spatie\DataTransferObject\Attributes\CastWith;";
+        $usesHeader["Casters"] = "use Spatie\DataTransferObject\Casters;";
+    }
+    $traits = [];
+
+    if (array_key_exists('authority', $vars)) {
+        $traits[] = "    use Traits\HasAuthority;";
+    }
+    if (array_key_exists('source', $vars)) {
+        $traits[] = "    use Traits\HasSource;";
+    }
+    if (array_key_exists('version', $vars)) {
+        $traits[] = "    use Traits\HasVersion;";
+    }
+    if (array_key_exists('language', $vars)) {
+        $traits[] = "    use Traits\HasLanguage;";
+    }
+    if (array_key_exists('change', $vars)) {
+        $traits[] = "    use Traits\HasChange;";
+    }
+    if (array_key_exists('register', $vars)) {
+        $traits[] = "    use Traits\HasRegister;";
     }
 
-    echo "
+    if (!empty($traits)) {
+        $usesHeader[] = "use Ivuorinen\BusinessDataFetcher\Traits;";
+    }
+
+    $usesString = implode("\n", $usesHeader);
+
+    $used = ['authority', 'source', 'version', 'language', 'change', 'register'];
+
+    $file = "<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+$usesString
+
 /**
- * $className
+ * $classNameString
  */
 class $className extends DataTransferObject
-{
-";
-    if (array_key_exists("source", $vars)) {
-        echo "    use HasSource;\n";
+{";
+    if (!empty($traits)) {
+        $file .= "\n" . implode("\n", $traits) . "\n";
     }
 
     foreach ($vars as $varKey => $varData) {
-        if ($varKey === "source") {
+        if (in_array($varKey, $used, true)) {
             continue;
         }
 
         $caster = "";
         if (str_contains($varData["type"], "[")) {
             $classType = str_replace(["[", "]", "?"], "", $varData["type"]);
-            $caster = "\n    #[CastWith(Casters\ArrayCaster::class, itemType: {$classType}::class)]";
+            $caster = "\n    #[CastWith(Casters\ArrayCaster::class, itemType: $classType::class)]";
         }
 
         $type = $varData["type"];
@@ -126,12 +165,26 @@ class $className extends DataTransferObject
         }
 
         $default = $varData["default"] !== null ? " = " . $varData["default"] . ";" : ";";
-        echo "
+
+        $file .= "
     /**
      * {$varData["docs"]}{$typeHelper}
      */{$caster}
-    public {$type} \${$varData["name"]}{$default}
+    public $type \${$varData["name"]}{$default}
 ";
     }
-    echo "\n}";
+    $file .= "}\n";
+
+    $files[$className] = $file;
+}
+
+if (!empty($files)) {
+    echo "Generating files:\n";
+
+    $dtoDir = sprintf('%s%s%s%s%s', dirname(__FILE__, 2), DS, 'src', DS, 'Dto');
+    foreach ($files as $className => $file) {
+        $filePath = sprintf('%s%s%s.php', $dtoDir, DS, $className);
+        echo $filePath . "\n";
+        file_put_contents($filePath, $file);
+    }
 }

phpstan.neon

@@ -0,0 +1,4 @@
+parameters:
+  level: 9
+  paths:
+    - src

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;
+}