Feature/200 add entity.section.* and entity.item.property.*

.php-cs-fixer.php

@@ -12,6 +12,7 @@
     ->in(__DIR__ . '/src/Services/CRM/Quote/')
     ->in(__DIR__ . '/src/Services/CRM/Lead/')
     ->in(__DIR__ . '/src/Services/CRM/Currency/')
+    ->in(__DIR__ . '/src/Services/Entity/Section/')
     ->name('*.php')
     ->exclude(['vendor', 'storage', 'docker', 'docs']) // Exclude directories
     ->ignoreDotFiles(true)

CHANGELOG.md

@@ -1,9 +1,22 @@
 # b24-php-sdk change log
 
+
 ## UPCOMING 1.5.0 – 2025.08.01
 
 ### Added
 
+- Added service `Services\Entity\Section\Service\Section` with support methods,
+  see [crm.entity.section.* methods](https://github.com/bitrix24/b24phpsdk/issues/200):
+    - `get` retrieve a list of storage sections, with batch calls support
+    - `add` add a storage section, with batch calls support
+    - `update` update a storage section, with batch calls support
+    - `delete` delete a storage section, with batch calls support
+- Added service `Services\Entity\Item\Property\Service\Section` with support methods:
+    - `get` retrieve a list of additional properties of storage elements, with batch calls support
+    - `add` add an additional property to storage elements, with batch calls support
+    - `update` update an additional property of storage elements, with batch calls support
+    - `delete` delete an additional property of storage elements, with batch calls support
+
 ### Fixed
 - Fixed typehints in Contact batch for method `add`, [see details](https://github.com/bitrix24/b24phpsdk/issues/202)
 

phpstan.neon.dist

@@ -26,6 +26,7 @@ parameters:
     - tests/Integration/Services/CRM/Quote/Service/QuoteProductRowsTest.php
     - tests/Integration/Services/CRM/Lead/Service/LeadUserfieldTest.php
     - tests/Integration/Services/CRM/Currency
+    - tests/Integration/Services/Entity/Section
   bootstrapFiles:
     - tests/bootstrap.php
   parallel:

rector.php

@@ -50,6 +50,8 @@
         __DIR__ . '/tests/Integration/Services/CRM/Quote/Service',
         __DIR__ . '/src/Services/CRM/Currency',
         __DIR__ . '/tests/Integration/Services/CRM/Currency',
+        __DIR__ . '/src/Services/Entity/Section',
+        __DIR__ . '/tests/Integration/Services/Entity/Section',
         __DIR__ . '/tests/Unit/',
     ])
     ->withCache(cacheDirectory: __DIR__ . '.cache/rector')

src/Core/Batch.php

@@ -34,6 +34,16 @@
  */
 class Batch implements BatchOperationsInterface
 {
+    protected const ENTITY_METHODS = [
+        'entity.item.delete',
+        'entity.section.delete',
+        'entity.item.get',
+        'entity.section.get',
+        'entity.item.update',
+        'entity.section.update',
+        'entity.item.property.update',
+    ];
+
     protected const MAX_BATCH_PACKET_SIZE = 50;
 
     protected const MAX_ELEMENTS_IN_PAGE = 50;
@@ -144,7 +154,7 @@ public function deleteEntityItems(
 
                 $parameters = $useFieldsInsteadOfId ? ['fields' => $itemId] : ['ID' => $itemId];
                 // TODO: delete after migration to RestAPI v2
-                if ($apiMethod === 'entity.item.delete') {
+                if (in_array($apiMethod, self::ENTITY_METHODS)) {
                     $parameters = array_merge($parameters, $additionalParameters);
                 }
 
@@ -218,7 +228,7 @@ public function updateEntityItems(string $apiMethod, array $entityItems): Genera
                     );
                 }
 
-                if ($apiMethod !== 'entity.item.update') {
+                if (!in_array($apiMethod, self::ENTITY_METHODS)) {
                     if (!array_key_exists('fields', $entityItem)) {
                         throw new InvalidArgumentException(
                             sprintf('array key «fields» not found in entity item with id %s', $entityItemId)
@@ -482,7 +492,7 @@ public function getTraversableList(
         // todo wait new api version
         if ($apiMethod !== 'user.get') {
             $defaultOrderKey = 'order';
-            $orderKey = $apiMethod === 'entity.item.get' ? 'SORT' : $defaultOrderKey;
+            $orderKey = in_array($apiMethod, self::ENTITY_METHODS) ? 'SORT' : $defaultOrderKey;
 
             $params = [
                 $orderKey => $this->getReverseOrder($order),

src/Services/Entity/EntityServiceBuilder.php

@@ -46,4 +46,34 @@ public function item(): Entity\Item\Service\Item
 
         return $this->serviceCache[__METHOD__];
     }
-}
+
+    public function section(): Entity\Section\Service\Section
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Entity\Section\Service\Section(
+                new Entity\Section\Service\Batch($this->batch, $this->log),
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
+
+    public function itemProperty(): Entity\Item\Property\Service\Property
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $batch = new Entity\Item\Property\Batch(
+                $this->core,
+                $this->log
+            );
+            $this->serviceCache[__METHOD__] = new Entity\Item\Property\Service\Property(
+                new Entity\Item\Property\Service\Batch($batch, $this->log),
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
+}

src/Services/Entity/Item/Property/Batch.php

@@ -0,0 +1,172 @@
+<?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\Entity\Item\Property;
+
+use Bitrix24\SDK\Core\Commands\Command;
+use Bitrix24\SDK\Core\Commands\CommandCollection;
+use Bitrix24\SDK\Core\Contracts\CoreInterface;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
+use Bitrix24\SDK\Core\Response\DTO\Pagination;
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+use Bitrix24\SDK\Core\Response\DTO\Result;
+use Bitrix24\SDK\Core\Response\DTO\Time;
+use Bitrix24\SDK\Core\Response\Response;
+use Generator;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Class Batch
+ *
+ * @package Bitrix24\SDK\Services\Entity\Item\Property
+ */
+class Batch extends \Bitrix24\SDK\Core\Batch
+{
+    /**
+     * Gets property items with batch call
+     *
+     *
+     * @return Generator<int, ResponseData>|ResponseData[]
+     * @throws \Bitrix24\SDK\Core\Exceptions\BaseException
+     */
+    public function getPropertyList(
+        string $apiMethod,
+        string $entity,
+        array $properyCodes
+    ): Generator {
+        $this->logger->debug(
+            'getProperyList.start',
+            [
+                'apiMethod' => $apiMethod,
+                'entity' => $entity,
+                'properyCodes' => $properyCodes,
+            ]
+        );
+
+        try {
+            $this->clearCommands();
+            foreach ($properyCodes as $cnt => $code) {
+                if (!is_string($code)) {
+                    throw new InvalidArgumentException(
+                        sprintf(
+                            'invalid type «%s» of property code «%s» at position %s, the code must be string type',
+                            gettype($code),
+                            $code,
+                            $cnt
+                        )
+                    );
+                }
+
+                $parameters = [
+                    'ENTITY' => $entity,
+                    'PROPERTY' => $code
+                ];
+                $this->registerCommand($apiMethod, $parameters);
+            }
+
+            foreach ($this->getTraversable(true) as $cnt => $propertyItemResult) {
+                yield $cnt => $propertyItemResult;
+            }
+        } catch (InvalidArgumentException $exception) {
+            $errorMessage = sprintf('batch get property items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+            throw $exception;
+        } catch (\Throwable $exception) {
+            $errorMessage = sprintf('batch get property items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+
+            throw new BaseException($errorMessage, $exception->getCode(), $exception);
+        }
+
+        $this->logger->debug('getProperyList.finish');
+    }
+
+    /**
+     * Delete property 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 => $itemId) {
+                if (!is_string($itemId)) {
+                    throw new InvalidArgumentException(
+                        sprintf(
+                            'invalid type «%s» of property code «%s» at position %s, the code must be string type',
+                            gettype($itemId),
+                            $itemId,
+                            $cnt
+                        )
+                    );
+                }
+
+                $parameters = ['PROPERTY' => $itemId];
+                $parameters = array_merge($parameters, $additionalParameters);
+
+                $this->registerCommand($apiMethod, $parameters);
+            }
+
+            foreach ($this->getTraversable(true) as $cnt => $deletedItemResult) {
+                yield $cnt => $deletedItemResult;
+            }
+        } catch (InvalidArgumentException $exception) {
+            $errorMessage = sprintf('batch delete property items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+            throw $exception;
+        } catch (\Throwable $exception) {
+            $errorMessage = sprintf('batch delete property 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/Entity/Item/Property/Result/PropertiesResult.php

@@ -0,0 +1,42 @@
+<?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\Entity\Item\Property\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class PropertiesResult extends AbstractResult
+{
+    /**
+     * @return PropertyItemResult[]
+     * @throws BaseException
+     */
+    public function getProperties(): array
+    {
+        $items = [];
+        $res = $this->getCoreResponse()->getResponseData()->getResult();
+        if (is_int(key($res))) {
+            // It was a call without PROPERTY arrtibute
+            foreach ($this->getCoreResponse()->getResponseData()->getResult() as $item) {
+                $items[] = new PropertyItemResult($item);
+            }
+        }
+        elseif (count($res) !== 0) {
+            // It was a call for one property only
+            $items[] = new PropertyItemResult($res);
+        }
+
+        return $items;
+    }
+}

src/Services/Entity/Item/Property/Result/PropertyItemResult.php

@@ -0,0 +1,26 @@
+<?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\Entity\Item\Property\Result;
+
+use Bitrix24\SDK\Services\CRM\Common\Result\AbstractCrmItem;
+
+/**
+ * @property-read string $ENTITY
+ * @property-read string $PROPERTY
+ * @property-read string $NAME
+ * @property-read string $TYPE
+ */
+class PropertyItemResult extends AbstractCrmItem
+{
+}