Support new ARES2 API

.gitattributes

@@ -1,7 +1,9 @@
 .github export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore
+.doc export-ignore
 changelog.md export-ignore
 tests export-ignore
 phpstan.neon export-ignore
 README.md export-ignore
+example export-ignore

.github/workflows/static-analysis.yml

@@ -0,0 +1,21 @@
+name: Static Analysis (only informative)
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  phpstan:
+    name: PHPStan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.0
+          coverage: none
+
+      - run: composer install --no-progress --prefer-dist
+      - run: composer phpstan -- --no-progress
+        continue-on-error: true # is only informative

.github/workflows/tests.yml

@@ -28,21 +28,36 @@ jobs:
           name: output
           path: tests/**/output
 
+  lowest_dependencies:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php: ['8.0', '8.1', '8.2']
+    name: PHP Lowest Dependencies ${{ matrix.php }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: curl, simplexml, json
+          coverage: none
 
-#  code_coverage:
-#    name: Code Coverage
-#    runs-on: ubuntu-latest
-#    steps:
-#      - uses: actions/checkout@v3
-#      - uses: shivammathur/setup-php@v2
-#        with:
-#          php-version: 8.0
-#          extensions: json, mbstring, tokenizer, fileinfo
-#          coverage: none
-#
-#      - run: composer install --no-progress --prefer-dist
-#      - run: vendor/bin/tester -p phpdbg tests -s -C --coverage ./coverage.xml --coverage-src ./src
-#      - run: wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.4.3/php-coveralls.phar
-#      - env:
-#          COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#        run: php php-coveralls.phar --verbose --config tests/.coveralls.yml
+      - run: composer update --no-progress --prefer-dist --prefer-lowest --prefer-stable
+      - run: composer tests
+
+  code_coverage:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.0
+          coverage: none
+
+      - run: composer install --no-progress --prefer-dist
+      - run: vendor/bin/tester -p phpdbg tests -s -C --coverage ./coverage.xml --coverage-src ./src
+      - run: wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.4.3/php-coveralls.phar
+      - env:
+          COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: php php-coveralls.phar --verbose --config tests/.coveralls.yml

.gitignore

@@ -1,3 +1,5 @@
 composer.lock
 /**/output/
 /vendor/
+/AresRestApi-verejne.json
+/coverage.html

README.md

@@ -1,5 +1,3 @@
-# Ares
-
 [![Downloads this Month](https://img.shields.io/packagist/dm/h4kuna/ares.svg)](https://packagist.org/packages/h4kuna/ares)
 [![Latest Stable Version](https://poser.pugx.org/h4kuna/ares/v/stable?format=flat)](https://packagist.org/packages/h4kuna/ares)
 [![Coverage Status](https://coveralls.io/repos/github/h4kuna/ares/badge.svg?branch=master)](https://coveralls.io/github/h4kuna/ares?branch=master)
@@ -8,54 +6,72 @@
 
 More information about versions is in [changelog](changelog.md).
 
+## Support development by QR code
+
+Use QR code or sponsor button where is link on my revolut.
+
+Thank you :)
+
+![QR payment](./.doc/payment.png)
+
+
 ## Installation to project
 
 The best way to install h4kuna/ares is using Composer:
+
 ```sh
-$ composer require h4kuna/ares
+composer require h4kuna/ares
 ```
 
 Download information about customer via his IN.
 
-## Example
+## ARES
+
+[Homepage](https://ares.gov.cz/) and official [ARES documentation](https://www.mfcr.cz/assets/attachments/2023-08-01_ARES-Technicka-dokumentace-Katalog-verejnych-sluzeb.pdf). And json [API](https://www.mfcr.cz/assets/attachments/2023-08-01_AresRestApi-verejne.json)
 
-Load data by one identification number
+Load data by one identification number.
 
 ```php
-$ares = (new h4kuna\Ares\AresFactory())->create();
+use h4kuna\Ares;
+$ares = (new Ares\AresFactory())->create();
 try {
     $response = $ares->loadBasic('87744473');
-    /* @var $response h4kuna\Ares\Basic\Data */
+    /* @var $response Ares\Ares\Core\Data */
     var_dump($response);
-} catch (h4kuna\Ares\Exceptions\IdentificationNumberNotFoundException $e) {
+} catch (Ares\Exceptions\IdentificationNumberNotFoundException $e) {
     // log identification number, why is bad? Or make nothing.
+} catch (Ares\Exceptions\ServerResponseException $e) {
+    // no response from server or broken json
 }
 ```
 
-Load data by many identification numbers
+Load data by many identification numbers. Limit by ARES service is set to 100 items, but library chunk it and check duplicity.
 
 ```php
-/** @var h4kuna\Ares\Ares $ares */
-$numbers = ['25596641', '26713250', '27082440', '11111111'];
-$res = $ares->loadBasicMulti($numbers);
+use h4kuna\Ares;
+/** @var Ares\Ares $ares */
+$numbers = ['one' => '25596641', 'two' => '26713250', 'three' => '27082440', 'four' => '11111111'];
 
-if ($res[$ares::RESULT_FAILED] !== []) {
-    var_dump($res[$ares::RESULT_FAILED]);
-}
-
-foreach ($res[$ares::RESULT_SUCCESS] as $r) {
-    var_dump($r->company);
+try { 
+    foreach ($ares->loadBasicMulti($numbers) as $name => $r) {
+        var_dump($name, $r->company);
+    }
+} catch (Ares\Exceptions\ServerResponseException $e) {
+    // no response from server or broken json
 }
 ```
 
-## Data Box
+## Data Box (datavá schánka)
+
+[Manual](https://www.mojedatovaschranka.cz/sds/p/download/sds_webove_sluzby.pdf#view=Fit)
 
 ```php
-/** @var h4kuna\Ares\Ares $ares */
+use h4kuna\Ares;
+/** @var Ares\Ares $ares */
 try {
     $response = $ares->loadDataBox('87744473');
     var_dump($response->ISDS);
-} catch (h4kuna\Ares\Exceptions\ConnectionException $e) {
+} catch (h4kuna\Ares\Exceptions\ServerResponseException $e) {
     // catch error
 }
 ```

bin/adis

@@ -0,0 +1,17 @@
+#!/usr/bin/env php
+<?php declare(strict_types=1);
+
+use h4kuna\Ares;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$TIN = trim($argv[1] ?? 'CZ27082440');
+
+$adis = (new Ares\AresFactory())->create()->getAdis();
+
+$subject = $adis->statusBusinessSubject($TIN);
+
+dump($subject);
+dump('Nalezen', $subject->exists);
+dump('Je spolehlivý plátce', $subject->reliable);
+dump('Je plátce DPH', $subject->isVatPayer);

bin/endpoints

@@ -0,0 +1,36 @@
+#!/usr/bin/env php
+<?php declare(strict_types=1);
+
+use h4kuna\Ares;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$IN = trim($argv[1] ?? '27082440');
+
+$ares = (new Ares\AresFactory())->create();
+try {
+	$response = $ares->loadBasic($IN);
+	/* @var $response Ares\Ares\Core\Data */
+	$response->original = null;
+	dump($response);
+} catch (Ares\Exceptions\IdentificationNumberNotFoundException $e) {
+	// log identification number, why is bad? Or make nothing.
+} catch (Ares\Exceptions\ServerResponseException $e) {
+	// no response from server or broken json
+}
+
+foreach ($response->sources as $name => $exists) {
+	if ($exists !== true || Ares\Ares\Helper::endpointExists($name) === false) {
+		continue;
+	}
+	dump(Ares\Ares\Helper::prepareUrl($name, $IN));
+
+	try {
+		$result = $ares->getAresClient()->useEndpoint($name, $IN);
+		dump($result);
+	} catch (Ares\Exceptions\IdentificationNumberNotFoundException $e) {
+		// log identification number, why is bad? Or make nothing.
+	} catch (Ares\Exceptions\ServerResponseException $e) {
+		// no response from server or broken json
+	}
+}

bin/legal-form

@@ -0,0 +1,16 @@
+#!/usr/bin/env php
+<?php declare(strict_types=1);
+
+use h4kuna\Ares;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$ares = (new Ares\AresFactory())->create();
+$result = $ares->getAresClient()->searchEndpoint(Ares\Ares\Sources::DIAL, [
+	'kodCiselniku' => 'PravniForma',
+	'zdrojCiselniku' => 'res',
+])->ciselniky[0]->polozkyCiselniku;
+
+foreach ($result as $item) {
+	dump($item);
+}

changelog.md

@@ -1,5 +1,56 @@
-v2.0.0
-======
+# v3.0.0
+
+- podpora nového API ARES2
+- v [bin](./bin) jsou spustitelné ukázky, jak se dostat na číselníky a jak na ostatní endpointy
+- pro IČO je vyžadován formát \d{8}, pokud je kratší, knihovna sama doplní nuly zleva
+- očekávám že se změní url API, pro tento případ je připravená `public static h4kuna\Ares\Ares\Helper::$baseUrl`, kterou lze nahradit, bez nutnosti vyčkávat na nový release
+- podobně lze dopnit nebo upravit url adresy endpointů
+- php 8.0+
+
+### Třidy
+
+- h4kuna\Ares\Ares
+  - metoda `loadBasic()` stále vrací [Data](./src/Ares/Core/Data.php)
+  - metoda `loadBasicMulti()` 
+    - nově vrací Generator nikoliv pole 
+    - vrací jen existující záznamy, třída Error byla smazána, nemá náhradu
+    - počet IČO není omezen, interně se rozdělí na dávky po 100, záznamech a ještě před tím se odeberou duplicity, při iteraci duplicity zůstanou, jen objekty budou mít stejné reference
+    - bylo zachováno pojmenování, vstupem je `['foo' => 123456]`, název `foo` bude jako klíč při iteraci
+
+
+- h4kuna\Ares\Ares\Core\Data
+  - zmizela metoda `psu()` bez náhrady, podobné informace jsou ve vlastnosti `$sources`
+  - zmizela metoda `isGroupVat()`, skupinové DPH nelze zjistit. Co se týče správnosti DIČ, [chystá se náprava](https://github.com/h4kuna/ares/issues/30#issuecomment-1719170527)
+  - odstraněné vlastnosti `$court`, `$file_number`, `$court_all` jsou dostupné na jiném endpointu, `Sources::SERVICE_VR`
+  - ~~DIČ je nově bez prefixu `CZ`~~, vlastnost `$tin` z důvodu zpětné kompatibility, prefix nese, ~~nová vlastnost `$vat_id` prefix nemá~~, vlastnost jsem odebral, `CZ` opět přidali
+  - vlastnost `$created` je podle mě momentálně rozbitá, pro [Alzu](https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/27082440) datumVzniku vrací `2023-09-04`, v registru ekonomických subjektů vrací [2003-08-26](https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty-res/27082440) (nahlášeno)
+  - byl změněn namespace pro `h4kuna\Ares\Basic\Data`, ale [aliases.php](./src/aliases.php) zajistí zpětnou kompatibilitu a bude hlásit aby jste si třídu přejmnovali, nicméně stará třída bude fungovat
+  - už není možnost do metody `toArray()` předat vlastní pole pro úpravu mapování
+  - přidané vlastnosti `$country` a `$country_code`
+
+- h4kuna\Ares\Exceptions\ConnectionException
+  - nastavena jako deprecated, zpětně funkční
+  - nahrazena h4kuna\Ares\Exceptions\ServerResponseException
+
+### Závěrem
+
+`Ares::loadBasic()` pokud si pohlídáte s jakými vlastnostmi pracujete a nebudou tam ty smazané, tak je to zpětně kompatibilní. Vstup je zpětně kompatibilní.
+
+`Ares::loadBasicMulti()` je potřeba vzít v potaz že to je zpětně nekompatibilní a nově se vrací Generator. Vstup je zpětně kompatibilní.
+
+Přidal jsem ADIS, služba která ověří zda se jedná o plátce DPH, identifikovanou osobu nebo neplátce DPH. U plátce vrátí, zda se jedná o spolehlivého plátce DPH. Ukázka je v [bin/adis](./bin/adis).
+
+### Chování validace pomocí ADIS
+
+|                      | ARES      | ADIS (Data::$adis::$exists) | Data::$vat_payer | Data::$tin | Spolehlivý plátce DPH Data::$adis::$reliable |
+|----------------------|-----------|-----------------------------|------------------|------------|----------------------------------------------|
+| Plátce DPH           | vrací DIČ | Existuje (true)             | true             | vyplněno   | true/false                                   |
+| Skupinové DPH        | vrátí DIČ | Neexistuje (false)          | true             | null       | null                                         |
+| Identifikovaná osoba | vrátí DIČ | Existuje (true)             | false            | vyplněno   | null                                         |
+| neplátce             | null      | null                        | false            | null       | null                                         |
+
+# v2.0.0
+
 - remove support php < 7.4
 - serialized date use RFC3339 instead of ISO8601, because ISO is deprecated by php
 - removed method Ares::getData()
@@ -10,19 +61,18 @@ v2.0.0
 - prepared AresFactory::create() for instance Ares class
 - Data::$tin is null if value is Skupinove_DPH
 
-v1.4.0
-======
+# v1.4.0
+
 - remove support php < 7.1
 - exceptions move to files -> one class is one file and change namespace
 
+# v1.3.0
 
-v1.3.0
-======
 - remove support for php 5.5
 - add Factory provide new instances Guzzle, Data, DataProvider
 
-v1.2.0
-======
+# v1.2.0
+
 - interface IData was removed
 - change data keys:
    - person -> is_person 
@@ -33,15 +83,15 @@ v1.2.0
 - class Data extends Messenger
 - class Data suggest property
 
-v1.1.3
-======
+# v1.1.3
+
 - method Ares::loadData throw IdentificationNumberNotFoundException if find nothing
 - rename InNotFoundExceptions -> IdentificationNumberNotFoundException
 - rename vat_pay -> vat_payer and interface IData
 - try download exists item if is faild try download item with non-exists parameter
 
-v1.1.2
-======
+# v1.1.2
+
 - method Ares::loadData throw InNotFoundExceptions if find nothing
 - attribute vat_pay in Data is bool instanceof empty string and string 1
 - attribute created in Data is Datetime instanceof ISO date