Feature/215 add crm documentgenerator numerator

.php-cs-fixer.php

@@ -15,12 +15,12 @@
     ->in(__DIR__ . '/src/Services/CRM/Requisites/')
     ->in(__DIR__ . '/src/Services/CRM/Status/')
     ->in(__DIR__ . '/src/Services/CRM/Timeline/')
+    ->in(__DIR__ . '/src/Services/CRM/Documentgenerator/Numerator/')
     ->in(__DIR__ . '/src/Services/Entity/Section/')
     ->in(__DIR__ . '/src/Services/Department/')
     ->in(__DIR__ . '/src/Services/Paysystem/')
     ->in(__DIR__ . '/src/Services/Sale/')
     ->in(__DIR__ . '/src/Services/Task/')
-    ->in(__DIR__ . '/src/Services/Sale/')
     ->name('*.php')
     ->exclude(['vendor', 'storage', 'docker', 'docs']) // Exclude directories
     ->ignoreDotFiles(true)

CHANGELOG.md

@@ -8,6 +8,14 @@
 
 ### Added
 
+- Added service `Services\CRM\Documentgenerator\Numerator` with support methods,
+  see [crm.documentgenerator.numerator.* methods](https://github.com/bitrix24/b24phpsdk/issues/215):
+    - `add` adds a new numerator, with batch calls support
+    - `list` gets the list of numerators, with batch calls support
+    - `update` updates an existing numbering with new values, with batch calls support
+    - `delete` deletes a numerator, with batch calls support
+    - `get` gets information about the numerator by its identifier
+    - `count` count numerators
 - Added service `Services\Paysystem\Handler\Service\Handler` with support methods,
   see [pay_system.handler.* methods](https://github.com/bitrix24/b24phpsdk/issues/260):
     - `add` adds a payment system handler

Makefile

@@ -259,7 +259,7 @@ test-integration-sale-payment-item-shipment:
 .PHONY: test-integration-sale-property-relation
 test-integration-sale-property-relation:
 	docker-compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sale_property_relation
- 
+
 .PHONY: test-integration-scope-crm
 test-integration-scope-crm:
 	docker-compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_scope_crm
@@ -356,6 +356,10 @@ integration_tests_sale_payment:
 integration_tests_sale_payment_item_basket:
 	docker-compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sale_payment_item_basket
 
+.PHONY: integration_tests_crm_documentgenerator_numerator
+integration_tests_crm_documentgenerator_numerator:
+	docker-compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_crm_documentgenerator_numerator
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:
@@ -411,4 +415,3 @@ build-examples-for-documentation:
 	--example-template=docs/api/file-templates/examples/master-example.php \
 	--openai-api-key=$(DOCUMENTATION_OPEN_AI_API_KEY) \
 	--docs-repo-folder=$(DOCUMENTATION_REPOSITORY_FOLDER)
-

phpstan.neon.dist

@@ -30,6 +30,7 @@ parameters:
     - tests/Integration/Services/CRM/Requisites
     - tests/Integration/Services/Task
     - tests/Integration/Services/Sale
+    - tests/Integration/Services/CRM/Documentgenerator/Numerator
   excludePaths:
     - tests/Integration/Services/CRM/Requisites/Service/RequisiteUserfieldUseCaseTest.php
     - tests/Integration/Services/CRM/Status

phpunit.xml.dist

@@ -169,6 +169,9 @@
         <testsuite name="integration_tests_sale_shipment_item">
             <directory>./tests/Integration/Services/Sale/ShipmentItem/</directory>
         </testsuite>
+        <testsuite name="integration_tests_crm_documentgenerator_numerator">
+            <directory>./tests/Integration/Services/CRM/Documentgenerator/Numerator/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

rector.php

@@ -64,6 +64,8 @@
         __DIR__ . '/tests/Integration/Services/Task',
         __DIR__ . '/src/Services/Sale',
         __DIR__ . '/tests/Integration/Services/Sale',
+        __DIR__ . '/src/Services/CRM/Documentgenerator/Numerator',
+        __DIR__ . '/tests/Integration/Services/CRM/Documentgenerator/Numerator',
         __DIR__ . '/tests/Unit/',
     ])
     ->withCache(cacheDirectory: __DIR__ . '.cache/rector')

src/Services/CRM/CRMServiceBuilder.php

@@ -653,4 +653,22 @@ public function timelineBindings(): Timeline\Bindings\Service\Bindings
 
         return $this->serviceCache[__METHOD__];
     }
+
+    public function documentgeneratorNumerator(): Documentgenerator\Numerator\Service\Numerator
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            // Use specialized Batch for Numerator to ensure correct REST parameter mapping (e.g., 'id')
+            $numeratorBatch = new Documentgenerator\Numerator\Batch(
+                $this->core,
+                $this->log
+            );
+            $this->serviceCache[__METHOD__] = new Documentgenerator\Numerator\Service\Numerator(
+                new Documentgenerator\Numerator\Service\Batch($numeratorBatch, $this->log),
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
 }

src/Services/CRM/Documentgenerator/Numerator/Batch.php

@@ -0,0 +1,93 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Vadim Soluyanov <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+use Generator;
+
+/**
+ * Class Batch
+ *
+ * @package Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator
+ */
+class Batch extends \Bitrix24\SDK\Core\Batch
+{
+    /**
+     * Delete entity items with batch call
+     *
+     *
+     * @return Generator<int, ResponseData>|ResponseData[]
+     * @throws \Bitrix24\SDK\Core\Exceptions\BaseException
+     */
+    public function deleteEntityItems(
+        string $apiMethod,
+        array $entityItemId,
+        ?array $additionalParameters = null
+    ): Generator {
+        $this->logger->debug(
+            'deleteEntityItems.start',
+            [
+                'apiMethod' => $apiMethod,
+                'entityItems' => $entityItemId,
+                'additionalParameters' => $additionalParameters,
+            ]
+        );
+
+        try {
+            $this->clearCommands();
+            foreach ($entityItemId as $cnt => $code) {
+                if (!is_int($code)) {
+                    throw new InvalidArgumentException(
+                        sprintf(
+                            'invalid type «%s» of numerator id «%s» at position %s, id must be integer type',
+                            gettype($code),
+                            $code,
+                            $cnt
+                        )
+                    );
+                }
+
+                $parameters = ['id' => $code];
+                $this->registerCommand($apiMethod, $parameters);
+            }
+
+            foreach ($this->getTraversable(true) as $cnt => $deletedItemResult) {
+                yield $cnt => $deletedItemResult;
+            }
+        } catch (InvalidArgumentException $exception) {
+            $errorMessage = sprintf('batch delete entity items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+            throw $exception;
+        } catch (\Throwable $exception) {
+            $errorMessage = sprintf('batch delete entity items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+
+            throw new BaseException($errorMessage, $exception->getCode(), $exception);
+        }
+
+        $this->logger->debug('deleteEntityItems.finish');
+    }
+}

src/Services/CRM/Documentgenerator/Numerator/Result/AddedNumeratorBatchResult.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result;
+
+use Bitrix24\SDK\Core\Result\AddedItemBatchResult;
+
+/**
+ * Class AddedNumeratorBatchResult
+ *
+ * @package Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result
+ */
+class AddedNumeratorBatchResult extends AddedItemBatchResult
+{
+    public function getId(): int
+    {
+        return (int)$this->getResponseData()->getResult()['numerator']['id'];
+    }
+}

src/Services/CRM/Documentgenerator/Numerator/Result/AddedNumeratorResult.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result;
+
+use Bitrix24\SDK\Core\Result\AddedItemResult;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+
+/**
+ * Class AddedNumeratorResult
+ *
+ * @package Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result
+ */
+class AddedNumeratorResult extends AddedItemResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function getId(): int
+    {
+        return (int)$this->getCoreResponse()->getResponseData()->getResult()['numerator']['id'];
+    }
+}

src/Services/CRM/Documentgenerator/Numerator/Result/DeletedNumeratorBatchResult.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result;
+
+use Bitrix24\SDK\Core\Result\DeletedItemBatchResult;
+
+/**
+ * Class DeletedNumeratorBatchResult
+ *
+ * @package Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result
+ */
+class DeletedNumeratorBatchResult extends DeletedItemBatchResult
+{
+    public function isSuccess(): bool
+    {
+        return (bool)$this->getResponseData()->getResult();
+    }
+}

src/Services/CRM/Documentgenerator/Numerator/Result/DeletedNumeratorResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\DeletedItemResult;
+
+/**
+ * Class DeletedNumeratorResult
+ *
+ * @package Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result
+ */
+class DeletedNumeratorResult extends DeletedItemResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function isSuccess(): bool
+    {
+        return (bool)$this->getCoreResponse()->getResponseData()->getResult();
+    }
+}

src/Services/CRM/Documentgenerator/Numerator/Result/NumeratorItemResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result;
+
+use Bitrix24\SDK\Services\CRM\Common\Result\AbstractCrmItem;
+
+/**
+ * Class NumeratorItemResult
+ *
+ * @property-read int $id
+ * @property-read string $name
+ * @property-read string $template
+ * @property-read array|null $settings
+ */
+class NumeratorItemResult extends AbstractCrmItem
+{
+}

src/Services/CRM/Documentgenerator/Numerator/Result/NumeratorResult.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Class NumeratorResult
+ *
+ * @package Bitrix24\SDK\Services\CRM\Documentgenerator\Numerator\Result
+ */
+class NumeratorResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function numerator(): NumeratorItemResult
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+        // Be tolerant to different API payload shapes
+        if (!empty($result['numerator']) && is_array($result['numerator'])) {
+            $result = $result['numerator'];
+        }
+
+        return new NumeratorItemResult($result);
+    }
+}