Merge pull request #398 from mesilov/feature/383-refactor-app-contracts-and-add-documentation-for-use-cases

refactor app contracts and add documentation for use cases

Author: mesilov

CHANGELOG.md

@@ -61,6 +61,8 @@
 
 ### Changed
 * ❗️ migrate from `ramsey/uuid` to `symfony/uid`
+* ❗️ refactor `Bitrix24\SDK\Application\Contracts`:
+
 * ❗️ update scope `telephony`, scope fully rewritten
     * `ExternalCall` – work with external call:
         * `getCallRecordUploadUrl` – get url for upload call record file

Makefile

@@ -10,7 +10,7 @@ lint-rector-fix:
 	vendor/bin/rector process
 
 test-unit:
-	vendor/bin/phpunit --testsuite unit_tests
+	vendor/bin/phpunit --testsuite unit_tests --display-warnings
 
 # integration tests with granularity by api-scope
 test-integration-scope-telephony:

README.md

@@ -7,13 +7,13 @@ A powerful PHP library for the Bitrix24 REST API
 
 ## Build status
 
-| CI\CD [status](https://github.com/mesilov/bitrix24-php-sdk/actions) on `master`                                                                                                                         | 
+| CI\CD [status](https://github.com/mesilov/bitrix24-php-sdk/actions) on `master`                                                                                                                       | 
 |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
 | [![phpstan check](https://github.com/mesilov/bitrix24-php-sdk/actions/workflows/phpstan.yml/badge.svg)](https://github.com/mesilov/bitrix24-php-sdk/actions/workflows/phpstan.yml)                    | 
 | [![unit-tests status](https://github.com/mesilov/bitrix24-php-sdk/actions/workflows/phpunit.yml/badge.svg)](https://github.com/mesilov/bitrix24-php-sdk/actions/workflows/phpunit.yml)                | 
 | [![integration-tests status](https://github.com/mesilov/bitrix24-php-sdk/actions/workflows/integration.yml/badge.svg)](https://github.com/mesilov/bitrix24-php-sdk/actions/workflows/integration.yml) | 
 
-Integration tests run in GitHub actions with real Bitrix24 portal 
+Integration tests run in GitHub actions with real Bitrix24 portal
 
 ## BITRIX24-PHP-SDK ✨FEATURES✨
 
@@ -23,8 +23,9 @@ Support both auth modes:
 - [x] work with incoming webhooks for simple integration projects for current portal
 
 Domain core events:
-  - [x] Access Token expired
-  - [x] Bitrix24 portal domain url changed
+
+- [x] Access Token expired
+- [x] Bitrix24 portal domain url changed
 
 API - level features
 
@@ -34,18 +35,10 @@ API - level features
 
 Performance improvements 🚀
 
-- Batch queries implemented with [PHP Generators](https://www.php.net/manual/en/language.generators.overview.php) – constant low memory and
-  low CPI usage
-    - [x] batch read data from bitrix24
-    - [x] batch write data to bitrix24
-    - [ ] write and read in one batch package
-    - [ ] composite batch queries to many entities (work in progress)
-- [ ] read without count flag
-
-Low-level tools to devs:
-- [ ] Rate-limit strategy
-- [ ] Retry strategy for safe methods
-
+- [x] Batch queries implemented with [PHP Generators](https://www.php.net/manual/en/language.generators.overview.php) – constant low memory and low CPI usage:
+- [x] batch read data from bitrix24
+- [x] batch write data to bitrix24
+- [x] read without count flag
 
 ## Development principles
 
@@ -67,6 +60,7 @@ Low-level tools to devs:
 - Reliable:
     - test coverage: unit, integration, contract
     - typical examples typical for different modes of operation and they are optimized for memory \ performance
+
 ## Architecture
 
 ### Abstraction layers
@@ -83,6 +77,7 @@ Low-level tools to devs:
     output: b24 response dto
     process: b24 entities, operate with immutable objects  
 ```
+
 ## Sponsors
 
 Help bitrix24-php-sdk by [boosty.to/bitrix24-php-sdk](https://boosty.to/bitrix24-php-sdk)
@@ -98,7 +93,9 @@ Help bitrix24-php-sdk by [boosty.to/bitrix24-php-sdk](https://boosty.to/bitrix24
 Add `"mesilov/bitrix24-php-sdk": "2.x"` to `composer.json` of your application. Or clone repo to your project.
 
 ## Examples
+
 ### Work with webhook
+
 ```php
 declare(strict_types=1);
 
@@ -121,17 +118,58 @@ var_dump($b24Service->getMainScope()->main()->getCurrentUserProfile()->getUserPr
 var_dump($b24Service->getCRMScope()->lead()->list([],[],['ID','TITLE'])->getLeads()[0]->TITLE);
 ```
 
+### Create application for Bitrix24 marketplace
+
+if you want to create application you can use production-ready contracts in namespace
+`Bitrix24\SDK\Application\Contracts`:
+
+- `Bitrix24Accounts` — Store auth tokens and
+  provides [methods](src/Application/Contracts/Bitrix24Accounts/Docs/Bitrix24Accounts.md) for work with Bitrix24
+  account.
+- `ApplicationInstallations` — Store information about [application installation](src/Application/Contracts/ApplicationInstallations/Docs/ApplicationInstallations.md), linked with Bitrix24 Account with auth
+  tokens. Optional can store links to:
+    - Client contact person: client person who responsible for application usage
+    - Bitrix24 Partner contact person: partner contact person who supports client and configure application
+    - Bitrix24 Partner: partner who supports client portal
+- `ContactPersons` – Store information [about person](src/Application/Contracts/ContactPersons/Docs/ContactPersons.md) who installed application.
+- `Bitrix24Partners` – Store information about [Bitrix24 Partner](src/Application/Contracts/Bitrix24Partners/Docs/Bitrix24Partners.md) who supports client portal and install or configure application. 
+
+Steps:
+1. Create own entity of this bounded contexts. 
+2. Implement all methods in contract interfaces.
+3. Test own implementation behavior with contract-tests `tests/Unit/Application/Contracts/*` – examples.
+
 ## Tests
 
 Tests locate in folder `tests` and we have two test types.
 In folder tests create file `.env.local` and fill environment variables from `.env`.
 
+### PHP Static Analysis Tool – phpstan
+
+Call in command line
+
+```shell
+make lint-phpstan
+```
+### PHP Static Analysis Tool – rector
+
+Call in command line for validate
+
+```shell
+make lint-rector
+```
+Call in command line for fix codebase
+
+```shell
+make lint-rector-fix
+```
+
 ### Unit tests
 
 **Fast**, in-memory tests without a network I\O For run unit tests you must call in command line
 
 ```shell
-composer phpunit-run-unit-test
+make test-unit
 ```
 
 ### Integration tests
@@ -142,12 +180,12 @@ composer phpunit-run-unit-test
 
 For run integration test you must:
 
-1. Create [new Bitrix24 portal](https://www.bitrix24.ru/create.php?p=255670) for development tests
-2. Go to left menu, click «Sitemap»
-3. Find menu item «Developer resources»
-4. Click on menu item «Other»
-5. Click on menu item «Inbound webhook»
-6. Assign all permisions with webhook and click «save» button
+1. Create new Bitrix24 portal for development tests.
+2. Go to left menu, click «Sitemap».
+3. Find menu item «Developer resources».
+4. Click on menu item «Other».
+5. Click on menu item «Inbound webhook».
+6. Assign all permisions with webhook and click «save» button.
 7. Create file `/tests/.env.local` with same settings, see comments in `/tests/.env` file.
 
 ```yaml
@@ -159,15 +197,10 @@ INTEGRATION_TEST_LOG_LEVEL=500
 8. call in command line
 
 ```shell
-composer composer phpunit-run-integration-tests
-```
-
-#### PHP Static Analysis Tool – phpstan
-
-Call in command line
-
-```shell
- composer phpstan-analyse
+make test-integration-core
+make test-integration-scope-telephony
+make test-integration-scope-workflows
+make test-integration-scope-user
 ```
 
 ## Submitting bugs and feature requests
@@ -182,16 +215,13 @@ bitrix24-php-sdk is licensed under the MIT License - see the `MIT-LICENSE.txt` f
 
 Maksim Mesilov - mesilov.maxim@gmail.com
 
-See also the list of [contributors](https://github.com/mesilov/bitrix24-php-sdk/graphs/contributors) which participated in this project.
+See also the list of [contributors](https://github.com/mesilov/bitrix24-php-sdk/graphs/contributors) which participated
+in this project.
 
 ## Need custom Bitrix24 application?
 
 mesilov.maxim@gmail.com for private consultations or dedicated support
 
 ## Documentation
 
-[Bitrix24 API documentation - Russian](http://dev.1c-bitrix.ru/rest_help/)
-
 [Bitrix24 API documentation - English](https://training.bitrix24.com/rest_help/)
-
-[Register new Bitrix24 account](https://www.bitrix24.ru/create.php?p=255670)

composer.json

@@ -17,17 +17,21 @@
     }
   ],
   "config": {
-    "sort-packages": true
+    "sort-packages": true,
+    "allow-plugins": {
+      "dealerdirect/phpcodesniffer-composer-installer": true
+    }
   },
   "require": {
     "php": "8.2.* || 8.3.*",
     "ext-json": "*",
-    "ext-bcmath": "*",
     "ext-curl": "*",
     "ext-intl": "*",
     "psr/log": "^2 || ^3",
-    "fig/http-message-util": "1.1.*",
-    "nesbot/carbon": "3.3.*",
+    "fig/http-message-util": "^1",
+    "giggsey/libphonenumber-for-php": "^8",
+    "darsyn/ip": "^4 || ^5",
+    "nesbot/carbon": "^3",
     "moneyphp/money": "^3 || ^4",
     "symfony/http-client": "^6 || ^7",
     "symfony/console": "^6 || ^7",
@@ -40,14 +44,16 @@
     "symfony/uid": "^6 || ^7"
   },
   "require-dev": {
-    "monolog/monolog": "3.5.*",
-    "phpstan/phpstan": "1.10.*",
-    "phpunit/phpunit": "11.0.*",
-    "symfony/debug-bundle": "7.0.*",
-    "symfony/stopwatch": "7.0.*",
+    "fakerphp/faker": "^1",
+    "monolog/monolog": "^3",
+    "nunomaduro/phpinsights": "^2",
+    "phpstan/phpstan": "1.11.7",
+    "phpunit/phpunit": "^10 || ^11",
+    "psalm/phar": "^5",
+    "rector/rector": "^1",
     "roave/security-advisories": "dev-master",
-    "fakerphp/faker": "1.23.*",
-    "rector/rector": "^1.0"
+    "symfony/debug-bundle": "^6 || ^7",
+    "symfony/stopwatch": "^6 || ^7"
   },
   "autoload": {
     "psr-4": {