Add enums and data filtering in CRM services

This commit introduces new enums for CRM Activity types and directions. Also, it adds a data filter class to handle field exclusion by prefix, and updates integration tests to use these new enums. These changes improve the code maintainability and readability in the CRM module.

Signed-off-by: mesilov <[email protected]>

src/Core/Fields/FieldsFilter.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Core\Fields;
+
+class FieldsFilter
+{
+    public function filterSystemFields(array $fieldCodes): array
+    {
+        $res = [];
+        foreach ($fieldCodes as $fieldCode) {
+            if (strncmp($fieldCode, 'UF_CRM_', 7) !== 0) {
+                $res[] = $fieldCode;
+            }
+        }
+
+        return $res;
+    }
+}

src/Services/CRM/Activity/ActivityContentType.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Activity;
+
+/**
+ * @see https://training.bitrix24.com/rest_help/crm/auxiliary/enum/crm_enum_contenttype.php
+ */
+enum ActivityContentType: int
+{
+    case default = 0;
+    case plainText = 1;
+    case bbCode = 2;
+    case html = 3;
+}

src/Services/CRM/Activity/ActivityDirectionType.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Activity;
+
+/**
+ * @see https://training.bitrix24.com/rest_help/crm/auxiliary/enum/crm_enum-activitydirection.php
+ */
+enum ActivityDirectionType: int
+{
+    case default = 0;
+    case incoming = 1;
+    case outgoing = 2;
+}

src/Services/CRM/Activity/ActivityNotifyType.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Activity;
+
+/**
+ * @see https://training.bitrix24.com/rest_help/crm/auxiliary/enum/crm_enumactivitynotifytype.php
+ */
+enum ActivityNotifyType: int
+{
+    case default = 0;
+    case minutes = 1;
+    case hours = 2;
+    case days = 3;
+}

src/Services/CRM/Activity/ActivityPriority.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Activity;
+
+/**
+ * @see https://training.bitrix24.com/rest_help/crm/auxiliary/enum/crm_enum_activitypriority.php
+ */
+enum ActivityPriority: int
+{
+    case default = 0;
+    case low = 1;
+    case medium = 2;
+    case high = 3;
+}

src/Services/CRM/Activity/ActivityStatus.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Activity;
+
+/**
+ * @see https://training.bitrix24.com/rest_help/crm/auxiliary/enum/crm_enum_activitystatus.php
+ */
+enum ActivityStatus: int
+{
+    case default = 0;
+    case waiting = 1;
+    case finished = 2;
+    case finishedAutomatically = 3;
+}

src/Services/CRM/Activity/ActivityType.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Activity;
+
+/**
+ * @see https://training.bitrix24.com/rest_help/crm/auxiliary/enum/crm_enum_activitytype.php
+ */
+enum ActivityType: int
+{
+    case default = 0;
+    case meeting = 1;
+    case call = 2;
+    case task = 3;
+    case letter = 4;
+    case action = 5;
+    case userAction = 6;
+}

src/Services/CRM/Activity/Result/ActivityItemResult.php

@@ -4,54 +4,62 @@
 
 namespace Bitrix24\SDK\Services\CRM\Activity\Result;
 
+use Bitrix24\SDK\Services\CRM\Activity\ActivityContentType;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityDirectionType;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityNotifyType;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityPriority;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityStatus;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityType;
 use Bitrix24\SDK\Services\CRM\Common\Result\AbstractCrmItem;
 use Carbon\CarbonImmutable;
+use Money\Currency;
+use Money\Money;
 
 /**
  * @see https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_fields.php
  *
- * @property-read int    $ID                        // Activity ID
- * @property-read int    $OWNER_ID
+ * @property-read int $ID                        // Activity ID
+ * @property-read int $OWNER_ID
  * @property-read string $OWNER_TYPE_ID
- * @property-read string $TYPE_ID
+ * @property-read ActivityType $TYPE_ID
  * @property-read string $PROVIDER_ID
  * @property-read string $PROVIDER_TYPE_ID
  * @property-read string $PROVIDER_GROUP_ID
- * @property-read int    $ASSOCIATED_ENTITY_ID      // ID of an entity associated with the activity
+ * @property-read int $ASSOCIATED_ENTITY_ID      // ID of an entity associated with the activity
  * @property-read string $SUBJECT
  * @property-read string $START_TIME
  * @property-read string $END_TIME                  // Completion time
- * @property-read string $DEADLINE                  // Deadline
- * @property-read string $COMPLETED                 // Completed
- * @property-read string $STATUS
- * @property-read string $RESPONSIBLE_ID
- * @property-read string $PRIORITY
- * @property-read string $NOTIFY_TYPE               // Notification type with crm_enum_activitynotifytype type
- * @property-read int    $NOTIFY_VALUE
+ * @property-read CarbonImmutable $DEADLINE                  // Deadline
+ * @property-read boolean $COMPLETED                 // Completed
+ * @property-read ActivityStatus $STATUS
+ * @property-read int $RESPONSIBLE_ID
+ * @property-read ActivityPriority $PRIORITY
+ * @property-read ActivityNotifyType $NOTIFY_TYPE               // Notification type with crm_enum_activitynotifytype type
+ * @property-read int $NOTIFY_VALUE
  * @property-read string $DESCRIPTION               // Description
- * @property-read string $DESCRIPTION_TYPE          // Description type with crm_enum_contenttype type
- * @property-read string $DIRECTION                 // with crm_enum_activitydirection type
- * @property-read string $LOCATION                  // Location
- * @property-read string $CREATED
- * @property-read string $AUTHOR_ID                 // Activity author ID
- * @property-read string $LAST_UPDATED              // Date of the last update date
- * @property-read string $EDITOR_ID                 // Editor
- * @property-read array  $SETTINGS
- * @property-read string $ORIGIN_ID
- * @property-read string $ORIGINATOR_ID
- * @property-read int    $RESULT_STATUS
- * @property-read int    $RESULT_STREAM
- * @property-read string $RESULT_SOURCE_ID
- * @property-read array  $PROVIDER_PARAMS
- * @property-read string $PROVIDER_DATA
- * @property-read int    $RESULT_MARK
- * @property-read string $RESULT_VALUE
- * @property-read string $RESULT_SUM
- * @property-read string $RESULT_CURRENCY_ID
- * @property-read int    $AUTOCOMPLETE_RULE         // Autocompletion
+ * @property-read ActivityContentType $DESCRIPTION_TYPE          // Description type with crm_enum_contenttype type
+ * @property-read ActivityDirectionType $DIRECTION                 // with crm_enum_activity direction type
+ * @property-read string|null $LOCATION                  // Location
+ * @property-read CarbonImmutable $CREATED
+ * @property-read int $AUTHOR_ID                 // Activity author ID
+ * @property-read CarbonImmutable $LAST_UPDATED              // Date of the last update date
+ * @property-read int $EDITOR_ID                 // Editor
+ * @property-read array $SETTINGS
+ * @property-read string|null $ORIGIN_ID
+ * @property-read string|null $ORIGINATOR_ID
+ * @property-read int $RESULT_STATUS
+ * @property-read int $RESULT_STREAM
+ * @property-read string|null $RESULT_SOURCE_ID
+ * @property-read array $PROVIDER_PARAMS
+ * @property-read string|null $PROVIDER_DATA
+ * @property-read int $RESULT_MARK
+ * @property-read string|null $RESULT_VALUE
+ * @property-read Money|null $RESULT_SUM
+ * @property-read Currency|null $RESULT_CURRENCY_ID
+ * @property-read int $AUTOCOMPLETE_RULE         // Autocompletion
  * @property-read string $BINDINGS                  // Bindings
- * @property-read array  $COMMUNICATIONS            // type crm_activity_communication
- * @property-read array  $FILES                     // Added files with diskfile type
+ * @property-read array $COMMUNICATIONS            // type crm_activity_communication
+ * @property-read array $FILES                     // Added files with diskfile type
  * @property-read string $WEBDAV_ELEMENTS
  */
 class ActivityItemResult extends AbstractCrmItem

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

@@ -5,6 +5,12 @@
 namespace Bitrix24\SDK\Services\CRM\Common\Result;
 
 use Bitrix24\SDK\Core\Result\AbstractItem;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityContentType;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityDirectionType;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityNotifyType;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityPriority;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityStatus;
+use Bitrix24\SDK\Services\CRM\Activity\ActivityType;
 use Bitrix24\SDK\Services\CRM\Common\Result\SystemFields\Types\Email;
 use Bitrix24\SDK\Services\CRM\Common\Result\SystemFields\Types\InstantMessenger;
 use Bitrix24\SDK\Services\CRM\Common\Result\SystemFields\Types\Phone;
@@ -29,17 +35,15 @@ class AbstractCrmItem extends AbstractItem
      */
     public function __get($offset)
     {
-        // todo унести в отдельный класс и покрыть тестами
-        // учитывать требования
-        //  - поддержка пользовательских полей с пользовательскими типами
-        //  - поддержка пользовательских полей со встроенными типами
-        //  - расширяемость для пользовательских полей в клиентском коде
-        //  - хранение связи поле-тип в аннотациях?
+        // todo move to separate service
+        //
+        //  - add user fields with custom user types
+        //  - add inheritance for user types
 
-        // приведение полей к реальным типам данных для основных сущностей CRM
         switch ($offset) {
             case 'ID':
             case 'ASSIGNED_BY_ID':
+            case 'RESPONSIBLE_ID':
             case 'CREATED_BY_ID':
             case 'MODIFY_BY_ID':
             case 'createdBy':
@@ -51,20 +55,24 @@ public function __get($offset)
             case 'opportunityAccount':
             case 'taxValueAccount':
             case 'taxValue':
-                // deal
             case 'LEAD_ID':
             case 'CONTACT_ID':
             case 'QUOTE_ID':
-                // productRow
             case 'OWNER_ID':
-                // DealCategoryItem
             case 'SORT':
             case 'id':
             case 'categoryId':
             case 'webformId':
             case 'assignedById':
             case 'contactId':
             case 'lastActivityBy':
+            case 'AUTHOR_ID':
+            case 'EDITOR_ID':
+            case 'RESULT_MARK':
+            case 'RESULT_STATUS':
+            case 'RESULT_STREAM':
+            case 'LAST_ACTIVITY_BY':
+            case 'ADDRESS_LOC_ADDR_ID':
                 if ($this->data[$offset] !== '' && $this->data[$offset] !== null) {
                     return (int)$this->data[$offset];
                 }
@@ -77,7 +85,6 @@ public function __get($offset)
                     return (int)$this->data[$offset];
                 }
                 return null;
-            // contact
             case 'EXPORT':
             case 'HAS_PHONE':
             case 'HAS_EMAIL':
@@ -94,9 +101,13 @@ public function __get($offset)
             case 'IS_REPEATED_APPROACH':
             case 'TAX_INCLUDED':
             case 'CUSTOMIZED':
+            case 'COMPLETED':
                 return $this->data[$offset] === 'Y';
             case 'DATE_CREATE':
             case 'CREATED_DATE':
+            case 'CREATED':
+            case 'DEADLINE':
+            case 'LAST_UPDATED':
             case 'DATE_MODIFY':
             case 'BIRTHDATE':
             case 'BEGINDATE':
@@ -105,22 +116,28 @@ public function __get($offset)
             case 'updatedTime':
             case 'movedTime':
             case 'lastActivityTime':
+            case 'LAST_ACTIVITY_TIME':
                 if ($this->data[$offset] !== '') {
                     return CarbonImmutable::createFromFormat(DATE_ATOM, $this->data[$offset]);
                 }
 
                 return null;
-            // deal
             case 'PRICE_EXCLUSIVE':
             case 'PRICE_NETTO':
             case 'PRICE_BRUTTO':
             case 'PRICE':
             case 'DISCOUNT_SUM':
+            case 'RESULT_SUM':
                 if ($this->data[$offset] !== '' && $this->data[$offset] !== null) {
                     $var = $this->data[$offset] * 100;
                     return new Money((string)$var, new Currency($this->currency->getCode()));
                 }
                 return null;
+            case 'RESULT_CURRENCY_ID':
+                if ($this->data[$offset] !== '' && $this->data[$offset] !== null) {
+                    return new Currency($this->data[$offset]);
+                }
+                return null;
             case 'PHONE':
                 if (!$this->isKeyExists($offset)) {
                     return [];
@@ -174,6 +191,18 @@ public function __get($offset)
                 return DiscountType::from($this->data[$offset]);
             case 'DISCOUNT_RATE':
                 return new Percentage((string)$this->data[$offset]);
+            case 'TYPE_ID':
+                return ActivityType::from((int)$this->data[$offset]);
+            case 'STATUS':
+                return ActivityStatus::from((int)$this->data[$offset]);
+            case 'PRIORITY':
+                return ActivityPriority::from((int)$this->data[$offset]);
+            case 'NOTIFY_TYPE':
+                return ActivityNotifyType::from((int)$this->data[$offset]);
+            case 'DESCRIPTION_TYPE':
+                return ActivityContentType::from((int)$this->data[$offset]);
+            case 'DIRECTION':
+                return ActivityDirectionType::from((int)$this->data[$offset]);
             default:
                 return $this->data[$offset] ?? null;
         }
@@ -187,7 +216,7 @@ public function __get($offset)
      * @return mixed|null
      * @throws UserfieldNotFoundException
      */
-    protected function getKeyWithUserfieldByFieldName(string $fieldName)
+    protected function getKeyWithUserfieldByFieldName(string $fieldName): mixed
     {
         if (!str_starts_with($fieldName, self::CRM_USERFIELD_PREFIX)) {
             $fieldName = self::CRM_USERFIELD_PREFIX . $fieldName;