Feature/583 add catalog.section v3

CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ### Added
 
+- Added service `Services\Catalog\Section` with support methods,
+  see [catalog.section.* methods](https://apidocs.bitrix24.com/api-reference/catalog/section/index.html) ([#583](https://github.com/bitrix24/b24phpsdk/issues/583)):
+    - `add` creates a new trade-catalog section, with batch calls support
+    - `update` updates an existing trade-catalog section, with batch calls support
+    - `get` gets a trade-catalog section by its identifier
+    - `list` gets the list of trade-catalog sections by filter
+    - `delete` deletes a trade-catalog section, with batch calls support
+    - `getFields` returns the description of trade-catalog section fields
 - Added service `Services\Catalog\Document` with support methods,
   see [catalog.document.* methods](https://apidocs.bitrix24.com/api-reference/catalog/document/index.html) ([#559](https://github.com/bitrix24/b24phpsdk/issues/559)):
     - `add` creates a new warehouse accounting document, with batch calls support

Makefile

@@ -943,6 +943,13 @@ test-integration-catalog-document-element:
 test-integration-catalog-document-element-annotations:
 	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_catalog_document_element_annotations
 
+.PHONY: test-integration-catalog-section
+test-integration-catalog-section:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_catalog_section
+.PHONY: test-integration-catalog-section-annotations
+test-integration-catalog-section-annotations:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_catalog_section_annotations
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

docs/testing.md

@@ -302,6 +302,8 @@ skip_violations:
 | `make test-integration-catalog-document-annotations` | Warehouse accounting document result annotations |
 | `make test-integration-catalog-document-element` | Warehouse accounting document line items |
 | `make test-integration-catalog-document-element-annotations` | Warehouse accounting document line item result annotations |
+| `make test-integration-catalog-section` | Trade-catalog sections |
+| `make test-integration-catalog-section-annotations` | Trade-catalog section result annotations |
 
 ### Tests — integration (Tasks)
 

phpunit.xml.dist

@@ -584,6 +584,12 @@
         <testsuite name="integration_tests_catalog_document_element_annotations">
             <file>./tests/Integration/Services/Catalog/DocumentElement/Result/DocumentElementItemResultTest.php</file>
         </testsuite>
+        <testsuite name="integration_tests_catalog_section">
+            <directory>./tests/Integration/Services/Catalog/Section/Service/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_catalog_section_annotations">
+            <file>./tests/Integration/Services/Catalog/Section/Result/SectionItemResultTest.php</file>
+        </testsuite>
     </testsuites>
     <source>
         <include>

rector.php

@@ -100,7 +100,7 @@
     ->withSets(
         [
             LevelSetList::UP_TO_PHP_84,
-            PHPUnitSetList::PHPUNIT_110
+            PHPUnitSetList::ANNOTATIONS_TO_ATTRIBUTES
         ]
     )
     ->withImportNames(
@@ -142,7 +142,6 @@
         \Rector\Naming\Rector\Foreach_\RenameForeachValueVariableToMatchExprVariableRector::class,
         \Rector\Naming\Rector\Foreach_\RenameForeachValueVariableToMatchMethodCallReturnTypeRector::class,
         \Rector\Php83\Rector\ClassConst\AddTypeToConstRector::class,
-        \Rector\Php84\Rector\Class_\DeprecatedAnnotationToDeprecatedAttributeRector::class,
         \Rector\Php84\Rector\Foreach_\ForeachToArrayAnyRector::class,
         \Rector\Php84\Rector\Foreach_\ForeachToArrayFindRector::class,
         \Rector\Php84\Rector\MethodCall\NewMethodCallWithoutParenthesesRector::class,

src/Services/Catalog/CatalogServiceBuilder.php

@@ -290,4 +290,20 @@ public function documentElement(): Catalog\DocumentElement\Service\DocumentEleme
 
         return $this->serviceCache[__METHOD__];
     }
+
+    public function section(): Catalog\Section\Service\Section
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Catalog\Section\Service\Section(
+                new Catalog\Section\Service\Batch(
+                    new Catalog\Section\Batch($this->core, $this->log),
+                    $this->log
+                ),
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
 }

src/Services/Catalog/Section/Batch.php

@@ -0,0 +1,108 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * 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\Catalog\Section;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+use Generator;
+
+/**
+ * Class Batch
+ *
+ * Overrides base Batch to handle parameter naming differences in catalog.section.* REST methods:
+ * - delete uses lowercase 'id' instead of 'ID'
+ *
+ * @see https://apidocs.bitrix24.com/api-reference/catalog/section/catalog-section-delete.html
+ * @see https://apidocs.bitrix24.com/api-reference/catalog/section/catalog-section-list.html
+ */
+class Batch extends \Bitrix24\SDK\Core\Batch
+{
+    /**
+     * Determines the ID key — lowercase 'id' for catalog section
+     */
+    #[\Override]
+    protected function determineKeyId(string $apiMethod, ?array $additionalParameters): string
+    {
+        return 'id';
+    }
+
+    /**
+     * Delete entity items with batch call using lowercase 'id' parameter
+     *
+     * @param int[]             $entityItemId
+     * @param array<mixed>|null $additionalParameters
+     *
+     * @return Generator<int, ResponseData>|ResponseData[]
+     * @throws BaseException
+     */
+    #[\Override]
+    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 => $itemId) {
+                if (!is_int($itemId)) {
+                    throw new InvalidArgumentException(
+                        sprintf(
+                            'invalid type «%s» of section id «%s» at position %s, section id must be integer type',
+                            gettype($itemId),
+                            $itemId,
+                            $cnt
+                        )
+                    );
+                }
+
+                $this->registerCommand($apiMethod, ['id' => $itemId]);
+            }
+
+            foreach ($this->getTraversable(true) as $cnt => $deletedItemResult) {
+                yield $cnt => $deletedItemResult;
+            }
+        } catch (InvalidArgumentException $exception) {
+            $errorMessage = sprintf('batch delete section items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+            throw $exception;
+        } catch (\Throwable $exception) {
+            $errorMessage = sprintf('batch delete section 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/Catalog/Section/Result/SectionAddedBatchResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * 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\Catalog\Section\Result;
+
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+
+class SectionAddedBatchResult
+{
+    public function __construct(private readonly ResponseData $responseData)
+    {
+    }
+
+    public function getResponseData(): ResponseData
+    {
+        return $this->responseData;
+    }
+
+    public function section(): SectionItemResult
+    {
+        return new SectionItemResult($this->responseData->getResult()['section']);
+    }
+}

src/Services/Catalog/Section/Result/SectionFieldsResult.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * 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\Catalog\Section\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class SectionFieldsResult extends AbstractResult
+{
+    /**
+     * @return array<string, array<string, mixed>>
+     * @throws BaseException
+     */
+    public function getFieldsDescription(): array
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult()['section'];
+    }
+}

src/Services/Catalog/Section/Result/SectionItemResult.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * 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\Catalog\Section\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractAnnotatedItem;
+
+/**
+ * @property-read int         $id
+ * @property-read int         $iblockId
+ * @property-read int|null    $iblockSectionId
+ * @property-read string      $name
+ * @property-read string|null $xmlId
+ * @property-read string|null $code
+ * @property-read int|null    $sort
+ * @property-read bool|null   $active
+ * @property-read string|null $description
+ * @property-read string|null $descriptionType
+ */
+class SectionItemResult extends AbstractAnnotatedItem
+{
+}

src/Services/Catalog/Section/Result/SectionResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * 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\Catalog\Section\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class SectionResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function section(): SectionItemResult
+    {
+        return new SectionItemResult($this->getCoreResponse()->getResponseData()->getResult()['section']);
+    }
+}

src/Services/Catalog/Section/Result/SectionUpdatedBatchResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * 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\Catalog\Section\Result;
+
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+
+class SectionUpdatedBatchResult
+{
+    public function __construct(private readonly ResponseData $responseData)
+    {
+    }
+
+    public function getResponseData(): ResponseData
+    {
+        return $this->responseData;
+    }
+
+    public function section(): SectionItemResult
+    {
+        return new SectionItemResult($this->responseData->getResult()['section']);
+    }
+}

src/Services/Catalog/Section/Result/SectionsResult.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * 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\Catalog\Section\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class SectionsResult extends AbstractResult
+{
+    /**
+     * @return SectionItemResult[]
+     * @throws BaseException
+     */
+    public function getSections(): array
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+
+        return array_map(
+            static fn (array $item): SectionItemResult => new SectionItemResult($item),
+            $result['sections'] ?? []
+        );
+    }
+}