Initial commit

src/BusinessDataFetcher.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\Exception\RequestException;
+use Ivuorinen\BusinessDataFetcher\Dto\BisCompanyDetails;
+use Ivuorinen\BusinessDataFetcher\Exceptions\ApiResponseErrorException;
+
+/**
+ * Fetches and returns business data from avoindata
+ */
+class BusinessDataFetcher
+{
+    /**
+     * @var \GuzzleHttp\Client
+     */
+    private Client $httpClient;
+
+    /**
+     * BusinessDataFetcher constructor.
+     */
+    public function __construct()
+    {
+        $this->httpClient = new Client([
+            'base_uri' => 'https://avoindata.prh.fi',
+            'timeout'  => 2,
+        ]);
+    }
+
+    /**
+     * Fetch Business Information.
+     *
+     * @param string $businessId
+     *
+     * @return array $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 {
+            $uri      = $requestUrl . '/' . $businessId;
+            $response = $this->httpClient->get($uri);
+
+            if ($response->getStatusCode() !== 200) {
+                throw new ApiResponseErrorException(
+                    $response->getReasonPhrase(),
+                    $response->getStatusCode()
+                );
+            }
+
+            $response_data = $this->parse_response($response);
+        } catch (RequestException $exception) {
+            throw new ApiResponseErrorException(
+                $exception->getMessage(),
+                $exception->getCode(),
+                $exception
+            );
+        }
+
+        return $response_data;
+    }
+
+    /**
+     * @param \Psr\Http\Message\ResponseInterface $response
+     *
+     * @return array
+     * @throws \JsonException
+     * @throws \Spatie\DataTransferObject\Exceptions\UnknownProperties
+     */
+    public function parse_response(\Psr\Http\Message\ResponseInterface $response): array
+    {
+        $data = json_decode(
+            $response->getBody()->getContents(),
+            true,
+            512,
+            JSON_THROW_ON_ERROR
+        );
+
+        $results = [];
+
+        foreach ($data['results'] as $result) {
+            $results[] = new BisCompanyDetails($result);
+        }
+
+        return $results;
+    }
+}

src/Dto/BisAddress.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Business Address
+ *
+ * - careOf (string, optional): Care of address
+ * - street (string, optional): Street address
+ * - postCode (string, optional): ZIP code
+ * - city (string, optional): City of address
+ * - language (string, optional): Two letter language code
+ * - type (integer): Type of address, 1 for street address, 2 for postal address
+ * - country (string, optional): Two letter country code
+ */
+class BisAddress extends DataTransferObject
+{
+    use HasSource;
+
+    /**
+     * One for current version and >1 for historical company names
+     *
+     * @var int
+     */
+    public int $version;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate = '';
+    /**
+     * Ending date of registration
+     *
+     * @var string|null
+     */
+    public ?string $endDate = null;
+    /**
+     * Care of address (c/o)
+     *
+     * @var string|null
+     */
+    public ?string $careOf;
+    /**
+     * Street address
+     *
+     * @var string|null
+     */
+    public ?string $street;
+    /**
+     * ZIP code
+     *
+     * @var string|null
+     */
+    public ?string $postCode;
+    /**
+     * City of address
+     *
+     * @var string|null
+     */
+    public ?string $city;
+    /**
+     * Two letter language code
+     *
+     * @var string|null
+     */
+    public ?string $language;
+    /**
+     * Type of address, 1 for street address, 2 for postal address
+     *
+     * @var int
+     */
+    public int $type;
+    /**
+     * Two-letter country code
+     *
+     * @var string|null
+     */
+    public ?string $country;
+}

src/Dto/BisCompanyBusinessIdChange.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Business ID Change
+ *
+ * - description (string): Description of reason
+ * - reason (string): Reason code
+ * - changeDate (string, optional): Date of Business ID change
+ * - change (integer):
+ *      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
+ * - oldBusinessId (string): Old Business ID
+ * - newBusinessId (string): New Business ID
+ * - language (string, optional): Two letter language code
+ */
+class BisCompanyBusinessIdChange extends DataTransferObject
+{
+    use HasSource;
+}

src/Dto/BisCompanyBusinessLine.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Business Line
+ *
+ * - order (integer): Zero for main line of business, positive for others
+ * - version (integer):
+ *      One for current version and
+ *      >1 for historical lines of business
+ * - registrationDate (string): Date of registration
+ * - endDate (string, optional): Ending date of registration
+ * - name (string): Name of line of business
+ * - language (string, optional): Two letter language code
+ */
+class BisCompanyBusinessLine extends DataTransferObject
+{
+    use HasSource;
+
+    /**
+     * Order
+     *
+     * Zero for primary company name,
+     * other for translations of the primary company name
+     * and auxiliary company names
+     *
+     * @var int
+     */
+    public int $order;
+    /**
+     * One for current version and >1 for historical company names
+     *
+     * @var int
+     */
+    public int $version;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate = '';
+    /**
+     * Ending date of registration
+     *
+     * @var string|null
+     */
+    public ?string $endDate = null;
+    /**
+     * Name of line of business
+     *
+     * @var string
+     */
+    public string $name;
+    /**
+     * Two letter language code
+     *
+     * @var string|null
+     */
+    public ?string $language = null;
+}

src/Dto/BisCompanyContactDetail.php

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

src/Dto/BisCompanyDetails.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Spatie\DataTransferObject\Attributes\CastWith;
+use Spatie\DataTransferObject\Casters;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Details
+ */
+class BisCompanyDetails extends DataTransferObject
+{
+    /**
+     * Business ID
+     *
+     * @var string
+     */
+    public string $businessId;
+    /**
+     * Primary company name
+     *
+     * @var string
+     */
+    public string $name;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate;
+    /**
+     * Company form
+     *
+     * @var string|null
+     */
+    public ?string $companyForm = null;
+    /**
+     * A URI for more details, if details aren't already included
+     *
+     * @var string|null
+     */
+    public ?string $detailsUri = null;
+
+    /**
+     * Primary company name and translations
+     *
+     * @var BisCompanyName[] $names
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyName::class)]
+    public ?array $names = null;
+
+    /**
+     * Auxiliary company name and translations
+     *
+     * @var BisCompanyName[] $auxiliaryNames
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyName::class)]
+    public ?array $auxiliaryNames = null;
+
+    /**
+     * Company's street and postal addresses
+     *
+     * @var BisAddress[]|null $addresses
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisAddress::class)]
+    public ?array $addresses = null;
+
+    /**
+     * Company form and translations
+     *
+     * @var BisCompanyForm[]|null $companyForms
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyForm::class)]
+    public ?array $companyForms = null;
+
+    /**
+     * Bankruptcy, liquidation or restructuring proceedings
+     *
+     * @var BisCompanyLiquidation[]|null $liquidations
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyLiquidation::class)]
+    public ?array $liquidations = null;
+
+    /**
+     * Company's lines of business and translations
+     *
+     * @var BisCompanyBusinessLine[]|null $businessLines
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyBusinessLine::class)]
+    public ?array $businessLines = null;
+
+    /**
+     * Company's language(s)
+     *
+     * @var BisCompanyLanguage[]|null $languages
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyLanguage::class)]
+    public ?array $languages = null;
+
+    /**
+     * Company's place of registered office and its translations
+     *
+     * @var BisCompanyRegisteredOffice[]|null $registeredOffices
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyRegisteredOffice::class)]
+    public ?array $registeredOffices = null;
+
+    /**
+     * Company's contact details and translations
+     *
+     * @var BisCompanyContactDetail[]|null $contactDetails
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyContactDetail::class)]
+    public ?array $contactDetails = null;
+
+    /**
+     * Company's registered entries
+     *
+     * @var BisCompanyRegisteredEntry[]|null $registeredEntries
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyRegisteredEntry::class)]
+    public ?array $registeredEntries = null;
+
+    /**
+     * Company's Business ID changes
+     *
+     * @var BisCompanyBusinessIdChange[]|null $businessIdChanges
+     */
+    #[CastWith(Casters\ArrayCaster::class, itemType: BisCompanyBusinessIdChange::class)]
+    public ?array $businessIdChanges = null;
+}

src/Dto/BisCompanyForm.php

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

src/Dto/BisCompanyLanguage.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Language
+ */
+class BisCompanyLanguage extends DataTransferObject
+{
+    use HasSource;
+
+    /**
+     * One for current version and >1 for historical company names
+     *
+     * @var int
+     */
+    public int $version;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate = '';
+    /**
+     * Ending date of registration
+     *
+     * @var string|null
+     */
+    public ?string $endDate = null;
+    /**
+     * Company name
+     *
+     * @var string
+     */
+    public string $name;
+    /**
+     * Two letter language code
+     *
+     * @var string|null
+     */
+    public ?string $language = null;
+}

src/Dto/BisCompanyLiquidation.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Liquidation
+ *
+ * - version (integer): One for current version and >1 for historical company forms
+ * - registrationDate (string): Date of registration
+ * - endDate (string, optional): Ending date of registration
+ * - name (string): Bankruptcy, liquidation or restructuring proceedings
+ * - language (string, optional): Two letter language code
+ * - type (string): Type of liquidation
+ */
+class BisCompanyLiquidation extends DataTransferObject
+{
+    use HasSource;
+
+    /**
+     * Order
+     *
+     * Zero for primary company name,
+     * other for translations of the primary company name
+     * and auxiliary company names
+     *
+     * @var int
+     */
+    public int $order;
+    /**
+     * One for current version and >1 for historical company names
+     *
+     * @var int
+     */
+    public int $version;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate = '';
+    /**
+     * Ending date of registration
+     *
+     * @var string|null
+     */
+    public ?string $endDate = null;
+    /**
+     * Bankruptcy, liquidation or restructuring proceedings
+     *
+     * @var string
+     */
+    public string $name;
+    /**
+     * Two letter language code
+     *
+     * @var string|null
+     */
+    public ?string $language = null;
+
+    public string $type;
+}

src/Dto/BisCompanyName.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Name
+ */
+class BisCompanyName extends DataTransferObject
+{
+    use HasSource;
+
+    /**
+     * Order
+     *
+     * Zero for primary company name,
+     * other for translations of the primary company name
+     * and auxiliary company names
+     *
+     * @var int
+     */
+    public int $order;
+    /**
+     * One for current version and >1 for historical company names
+     *
+     * @var int
+     */
+    public int $version;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate = '';
+    /**
+     * Ending date of registration
+     *
+     * @var string|null
+     */
+    public ?string $endDate = null;
+    /**
+     * Company name
+     *
+     * @var string
+     */
+    public string $name;
+    /**
+     * Two letter language code
+     *
+     * @var string|null
+     */
+    public ?string $language = null;
+}

src/Dto/BisCompanyRegisteredEntry.php

@@ -0,0 +1,108 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Exceptions\UnexpectedValueException;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Registered Entry
+ */
+class BisCompanyRegisteredEntry extends DataTransferObject
+{
+    /**
+     * Description of entry
+     *
+     * @var string
+     */
+    public string $description;
+    /**
+     * Zero for common entries, one for ‘Unregistered’ and two for ‘Registered’
+     *
+     * @see getStatusText()
+     *
+     * @var int
+     */
+    public int $status;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate;
+    /**
+     * Ending date of registration
+     *
+     * @var string|null
+     */
+    public ?string $endDate;
+    /**
+     * register (integer):
+     * - 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()
+     *
+     * @var int
+     */
+    public int $register;
+    /**
+     * Two letter language code
+     *
+     * @var string|null
+     */
+    public ?string $language;
+    /**
+     * authority (integer):
+     * - 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

@@ -0,0 +1,51 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Dto;
+
+use Ivuorinen\BusinessDataFetcher\Traits\HasSource;
+use Spatie\DataTransferObject\DataTransferObject;
+
+/**
+ * Company Registered Office
+ */
+class BisCompanyRegisteredOffice extends DataTransferObject
+{
+    use HasSource;
+
+    /**
+     * Zero for primary place of registered office, positive for others
+     *
+     * @var int
+     */
+    public int $order;
+    /**
+     * One for current version and >1 for historical places of registered office
+     *
+     * @var int
+     */
+    public int $version;
+    /**
+     * Date of registration
+     *
+     * @var string
+     */
+    public string $registrationDate;
+    /**
+     * Ending date of registration
+     *
+     * @var string|null
+     */
+    public ?string $endDate;
+    /**
+     * Name of place of registered office
+     *
+     * @var string
+     */
+    public string $name;
+    /**
+     * Two letter language code
+     *
+     * @var string|null
+     */
+    public ?string $language;
+}

src/Exceptions/ApiResponseErrorException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Exceptions;
+
+class ApiResponseErrorException extends \Exception {}

src/Exceptions/UnexpectedValueException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Exceptions;
+
+class UnexpectedValueException extends \Exception {}

src/Traits/HasSource.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Ivuorinen\BusinessDataFetcher\Traits;
+
+trait HasSource
+{
+    /**
+     * Source of the information.
+     *
+     * source (integer, optional):
+     * - Zero for common,
+     * - one for Finnish Patent and Registration Office,
+     * - two for Tax Administration or
+     * - three for Business Information System
+     *
+     * Use `getSourceText()` to get the text representation.
+     *
+     * @see getSourceText()
+     *
+     * @var int|null
+     */
+    public ?int $source;
+
+    public function getSourceText(): string
+    {
+        return match ($this->source) {
+            0 => 'common',
+            1 => 'Finnish Patent and Registration Office',
+            2 => 'Tax Administration',
+            3 => 'Business Information System',
+            default => '',
+        };
+    }
+}