Add support for entity service in SDK

CHANGELOG.md

@@ -1,9 +1,23 @@
 # b24-php-sdk change log
 
-## Unreleased 1.3.0 – 2025.01.19
+## Unreleased 1.3.0 – 2025.02.03
 
 ### Added
 
+- Added support new scope `entity`
+- Added service `Services\Entity\Service\Item` with support methods,
+  see [fix entity.item.* methods](https://github.com/bitrix24/b24phpsdk/issues/53):
+    - `get` get item, with batch calls support
+    - `add` add new item, with batch calls support
+    - `delete` delete item, with batch calls support
+    - `update`  update item, with batch calls support
+- Added service `Services\Entity\Service\Entity` with support methods,
+  see [fix entity.* methods](https://github.com/bitrix24/b24phpsdk/issues/53):
+    - `get` get entity
+    - `add` add new entity
+    - `delete` delete entity
+    - `update` update entity
+    - `rights` get or change access permissions
 - Added new application scope nodes `humanresources.hcmlink` and `sign.b2e`
 - Added method `Bitrix24\SDK\Core\Credentials\Scope::contains` for check is current scope code contains in scope, for
   task «[split cli commands](https://github.com/bitrix24/b24phpsdk/issues/92)»
@@ -59,6 +73,8 @@
 
 - Fixed errors in `Bitrix24\SDK\Core\Batch` for method
   `user.get`, [see details](https://github.com/bitrix24/b24phpsdk/issues/103)
+- Fixed errors in `Bitrix24\SDK\Core\Batch` for methods `entity.item.get` and
+  `entity.item.update`, [see details](https://github.com/bitrix24/b24phpsdk/issues/53)
 
 ### Statistics
 

Makefile

@@ -127,4 +127,6 @@ test-integration-scope-user:
 test-integration-scope-user-consent:
 	vendor/bin/phpunit --testsuite integration_tests_scope_user_consent
 test-integration-core:
-	vendor/bin/phpunit --testsuite integration_tests_core
+	vendor/bin/phpunit --testsuite integration_tests_core
+test-integration-scope-entity:
+	vendor/bin/phpunit --testsuite integration_tests_scope_entity

phpunit.xml.dist

@@ -37,6 +37,9 @@
         <testsuite name="integration_tests_scope_workflows">
             <directory>./tests/Integration/Services/Workflows/</directory>
         </testsuite>
+        <testsuite name="integration_tests_scope_entity">
+            <directory>./tests/Integration/Services/Entity/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

src/Core/Batch.php

@@ -108,18 +108,21 @@ public function addEntityItems(string $apiMethod, array $entityItems): Generator
     /**
      * Delete entity items with batch call
      *
-     * @param array<int, int> $entityItemId
      *
      * @return Generator<int, ResponseData>|ResponseData[]
      * @throws \Bitrix24\SDK\Core\Exceptions\BaseException
      */
-    public function deleteEntityItems(string $apiMethod, array $entityItemId): Generator
-    {
+    public function deleteEntityItems(
+        string $apiMethod,
+        array $entityItemId,
+        ?array $additionalParameters = null
+    ): Generator {
         $this->logger->debug(
             'deleteEntityItems.start',
             [
                 'apiMethod' => $apiMethod,
                 'entityItems' => $entityItemId,
+                'additionalParameters' => $additionalParameters,
             ]
         );
 
@@ -137,7 +140,12 @@ public function deleteEntityItems(string $apiMethod, array $entityItemId): Gener
                     );
                 }
 
-                $this->registerCommand($apiMethod, ['ID' => $itemId]);
+                $parameters = ['ID' => $itemId];
+                if ($apiMethod === 'entity.item.delete') {
+                    $parameters = array_merge($parameters, $additionalParameters);
+                }
+
+                $this->registerCommand($apiMethod, $parameters);
             }
 
             foreach ($this->getTraversable(true) as $cnt => $deletedItemResult) {
@@ -204,18 +212,22 @@ public function updateEntityItems(string $apiMethod, array $entityItems): Genera
                     );
                 }
 
-                if (!array_key_exists('fields', $entityItem)) {
-                    throw new InvalidArgumentException(
-                        sprintf('array key «fields» not found in entity item with id %s', $entityItemId)
-                    );
-                }
+                if ($apiMethod !== 'entity.item.update') {
+                    if (!array_key_exists('fields', $entityItem)) {
+                        throw new InvalidArgumentException(
+                            sprintf('array key «fields» not found in entity item with id %s', $entityItemId)
+                        );
+                    }
 
-                $cmdArguments = [
-                    'id' => $entityItemId,
-                    'fields' => $entityItem['fields']
-                ];
-                if (array_key_exists('params', $entityItem)) {
-                    $cmdArguments['params'] = $entityItem['params'];
+                    $cmdArguments = [
+                        'id' => $entityItemId,
+                        'fields' => $entityItem['fields']
+                    ];
+                    if (array_key_exists('params', $entityItem)) {
+                        $cmdArguments['params'] = $entityItem['params'];
+                    }
+                } else {
+                    $cmdArguments = $entityItem;
                 }
 
                 $this->registerCommand($apiMethod, $cmdArguments);
@@ -397,7 +409,10 @@ public function getTraversableList(
         }
 
         $keyId = $isCrmItemsInBatch ? 'id' : 'ID';
-
+        $this->logger->debug('getTraversableList.getFirstPage', [
+            'apiMethod' => $apiMethod,
+            'params' => $params,
+        ]);
         $response = $this->core->call($apiMethod, $params);
         $totalElementsCount = $response->getResponseData()->getPagination()->getTotal();
         $this->logger->debug('getTraversableList.totalElementsCount', [
@@ -453,8 +468,11 @@ public function getTraversableList(
         // getLastElementId in filtered result
         // todo wait new api version
         if ($apiMethod !== 'user.get') {
+            $defaultOrderKey = 'order';
+            $orderKey = $apiMethod === 'entity.item.get' ? 'SORT' : $defaultOrderKey;
+
             $params = [
-                'order' => $this->getReverseOrder($order),
+                $orderKey => $this->getReverseOrder($order),
                 'filter' => $filter,
                 'select' => $select,
                 'start' => 0,
@@ -474,25 +492,30 @@ public function getTraversableList(
             $params = array_merge($params, $additionalParameters);
         }
 
+        $this->logger->debug('getTraversableList.getLastPage', [
+            'apiMethod' => $apiMethod,
+            'params' => $params,
+        ]);
         $lastResultPage = $this->core->call($apiMethod, $params);
         if ($isCrmItemsInBatch) {
             $lastElementId = (int)$lastResultPage->getResponseData()->getResult()['items'][0][$keyId];
         } else {
             $lastElementId = (int)$lastResultPage->getResponseData()->getResult()[0][$keyId];
         }
 
-        // reverse order if you need
+        $this->logger->debug('getTraversableList.lastElementsId', [
+            'lastElementIdInFirstPage' => $lastElementIdInFirstPage,
+            'lastElementIdInLastPage' => $lastElementId,
+        ]);
+
+
+        // reverse order if elements in batch ordered in DESC direction
         if ($lastElementIdInFirstPage > $lastElementId) {
             $tmp = $lastElementIdInFirstPage;
             $lastElementIdInFirstPage = $lastElementId;
             $lastElementId = $tmp;
         }
 
-        $this->logger->debug('getTraversableList.lastElementsId', [
-            'lastElementIdInFirstPage' => $lastElementIdInFirstPage,
-            'lastElementId' => $lastElementId,
-        ]);
-
         // register commands with updated filter
         //more than one page in results -  register list commands
         ++$lastElementIdInFirstPage;

src/Core/Contracts/BatchOperationsInterface.php

@@ -76,7 +76,11 @@ public function addEntityItems(string $apiMethod, array $entityItems): Generator
      * @return Generator<int, ResponseData>|ResponseData[]
      * @throws BaseException
      */
-    public function deleteEntityItems(string $apiMethod, array $entityItemId): Generator;
+    public function deleteEntityItems(
+        string $apiMethod,
+        array $entityItemId,
+        ?array $additionalParameters = null
+    ): Generator;
 
     /**
      * Update entity items with batch call

src/Services/AbstractService.php

@@ -55,4 +55,14 @@ protected function guardPositiveId(int $id): void
             throw new InvalidArgumentException(sprintf('id must be positive, current value: %s', $id));
         }
     }
+
+    /**
+     * @throws InvalidArgumentException
+     */
+    protected function guardNonEmptyString(string $value, ?string $message = null): void
+    {
+        if (trim($value) === '') {
+            throw new InvalidArgumentException($message ?? 'value must be non empty');
+        }
+    }
 }

src/Services/CRM/Common/Result/AbstractCrmItem.php

@@ -141,6 +141,8 @@ public function __get($offset)
             case 'LAST_ACTIVITY_TIME':
             case 'START_TIME':
             case 'END_TIME':
+            case 'DATE_ACTIVE_FROM':
+            case 'DATE_ACTIVE_TO':
             case 'TIMESTAMP_X':
                 if ($this->data[$offset] !== '') {
                     return CarbonImmutable::createFromFormat(DATE_ATOM, $this->data[$offset]);

src/Services/Entity/Entity/Result/AddedEntityResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@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\Entity\Entity\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class AddedEntityResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function isSuccess(): bool
+    {
+        return (bool)$this->getCoreResponse()->getResponseData()->getResult()[0];
+    }
+}

src/Services/Entity/Entity/Result/EntitiesResult.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@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\Entity\Entity\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class EntitiesResult extends AbstractResult
+{
+    /**
+     * @return EntityItemResult[]
+     * @throws BaseException
+     */
+    public function getEntities(): array
+    {
+        $res = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult() as $item) {
+            $res[] = new EntityItemResult($item);
+        }
+
+        return $res;
+    }
+}

src/Services/Entity/Entity/Result/EntityItemResult.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@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\Entity\Entity\Result;
+
+use Bitrix24\SDK\Services\Catalog\Common\ProductType;
+use Bitrix24\SDK\Services\Catalog\Common\Result\AbstractCatalogItem;
+use Bitrix24\SDK\Services\CRM\Common\Result\AbstractCrmItem;
+use Carbon\CarbonImmutable;
+use Money\Currency;
+use Money\Money;
+
+/**
+ * @property-read int $ID
+ * @property-read string $IBLOCK_TYPE_ID
+ * @property-read string $ENTITY
+ * @property-read string $NAME
+ */
+class EntityItemResult extends AbstractCrmItem
+{
+}

src/Services/Entity/Entity/Result/EntityRightsResult.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@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\Entity\Entity\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class EntityRightsResult extends AbstractResult
+{
+    public function getRights(): array
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult();
+    }
+}

src/Services/Entity/Entity/Service/Batch.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Maksim Mesilov <mesilov.maxim@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\Entity\Entity\Service;
+
+use Bitrix24\SDK\Core\Contracts\BatchOperationsInterface;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AddedItemBatchResult;
+use Bitrix24\SDK\Core\Result\DeletedItemBatchResult;
+use Bitrix24\SDK\Core\Result\UpdatedItemBatchResult;
+use Generator;
+use Psr\Log\LoggerInterface;
+
+readonly class Batch
+{
+    public function __construct(
+        protected BatchOperationsInterface $batch,
+        protected LoggerInterface          $log)
+    {
+    }
+}