Dev

CHANGELOG.md

@@ -1,16 +1,28 @@
 # bitrix24-php-sdk change log
 
-## 2.0-alpha.5 – 26.11.2021
+## 2.0-alpha.5 – 28.11.2021
 
 ### Added
 
 * add method `countByFilter` for all related services, see
   issue [Добавить для всех сущностей метод подсчёта количества элементов по фильтру #228](https://github.com/mesilov/bitrix24-php-sdk/issues/228)
+* add in scope «CRM» Userfield service and integration test
+* add in scope «CRM» ContactUserfield service and integration test, see
+  issue [Добавить сервис по работе с юзерфилдами контакта #231](https://github.com/mesilov/bitrix24-php-sdk/issues/231)
+* add method getUserfieldByFieldName for `ContactItemResult`
+* add in scope «CRM» DealUserfield service and integration test, see
+  issue [Добавить сервис по работе с юзерфилдами cделки #232](https://github.com/mesilov/bitrix24-php-sdk/issues/232) 
+* add method getUserfieldByFieldName for `DealItemResult`
+* add exception `UserfieldNotFoundException`
 
 ### Removed
 
 * remove all `0.*` and `1.*` code from `2.*` branch
 
+### Changed
+
+* update type definition for `ContactItemResult`, now return types will be cast to real types: DateTimeInterface, int, boolean etc
+
 ## 2.0-alpha.4 – 25.11.2021
 
 ### Changed

src/Core/Credentials/Scope.php

@@ -16,11 +16,12 @@ class Scope
     /**
      * @var string[]
      */
-    protected $availableScope = [
+    protected array $availableScope = [
         'app',
         'bizproc',
         'calendar',
         'call',
+        'catalog',
         'contact_center',
         'crm',
         'delivery',
@@ -60,7 +61,7 @@ class Scope
     /**
      * @var array
      */
-    protected $currentScope = [];
+    protected array $currentScope = [];
 
     /**
      * Scope constructor.

src/Core/Result/AbstractItem.php

@@ -13,7 +13,7 @@
  */
 abstract class AbstractItem implements \IteratorAggregate
 {
-    private array $data;
+    protected array $data;
 
     /**
      * AbstractItem constructor.
@@ -75,4 +75,14 @@ public function getIterator()
     {
         return new \ArrayIterator($this->data);
     }
+
+    /**
+     * @param string $key
+     *
+     * @return bool
+     */
+    protected function isKeyExists(string $key): bool
+    {
+        return array_key_exists($key, $this->data);
+    }
 }

src/Services/CRM/CRMServiceBuilder.php

@@ -70,6 +70,21 @@ public function deal(): Deal\Service\Deal
         return $this->serviceCache[__METHOD__];
     }
 
+    /**
+     * @return \Bitrix24\SDK\Services\CRM\Deal\Service\DealUserfield
+     */
+    public function dealUserfield(): Deal\Service\DealUserfield
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Deal\Service\DealUserfield(
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
+
     /**
      * @return Contact\Service\Contact
      */
@@ -86,6 +101,21 @@ public function contact(): Contact\Service\Contact
         return $this->serviceCache[__METHOD__];
     }
 
+    /**
+     * @return \Bitrix24\SDK\Services\CRM\Contact\Service\ContactUserfield
+     */
+    public function contactUserfield(): Contact\Service\ContactUserfield
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Contact\Service\ContactUserfield(
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
+
     /**
      * @return Deal\Service\DealProductRows
      */
@@ -125,4 +155,19 @@ public function product(): Product\Service\Product
 
         return $this->serviceCache[__METHOD__];
     }
+
+    /**
+     * @return Userfield\Service\Userfield
+     */
+    public function userfield(): Userfield\Service\Userfield
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Userfield\Service\Userfield(
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
 }

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

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Common\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+use Bitrix24\SDK\Services\CRM\Userfield\Exceptions\UserfieldNotFoundException;
+use DateTimeImmutable;
+
+class AbstractCrmItem extends AbstractItem
+{
+    private const CRM_USERFIELD_PREFIX = 'UF_CRM_';
+
+    /**
+     * @param int|string $offset
+     *
+     * @return bool|\DateTimeImmutable|int|mixed|null
+     */
+    public function __get($offset)
+    {
+        // todo унести в отдельный класс и покрыть тестами
+        // приведение полей к реальным типам данных для основных сущностей CRM
+        switch ($offset) {
+            case 'ID':
+            case 'ASSIGNED_BY_ID':
+            case 'CREATED_BY_ID':
+            case 'MODIFY_BY_ID':
+                // deal
+            case 'LEAD_ID':
+            case 'CONTACT_ID':
+            case 'QUOTE_ID':
+                if ($this->data[$offset] !== '' && $this->data[$offset] !== null) {
+                    return (int)$this->data[$offset];
+                }
+
+                return null;
+            case 'COMPANY_ID':
+                if ($this->data[$offset] !== '' && $this->data[$offset] !== null && $this->data[$offset] !== '0') {
+                    return (int)$this->data[$offset];
+                }
+
+                return null;
+
+            // contact
+            case 'EXPORT':
+            case 'HAS_PHONE':
+            case 'HAS_EMAIL':
+            case 'HAS_IMOL':
+            case 'OPENED':
+                // deal
+            case 'IS_MANUAL_OPPORTUNITY':
+            case 'CLOSED':
+            case 'IS_NEW':
+            case 'IS_RECURRING':
+            case 'IS_RETURN_CUSTOMER':
+            case 'IS_REPEATED_APPROACH':
+                return $this->data[$offset] === 'Y';
+            case 'DATE_CREATE':
+            case 'DATE_MODIFY':
+            case 'BIRTHDATE':
+            case 'BEGINDATE':
+            case 'CLOSEDATE':
+                if ($this->data[$offset] !== '') {
+                    return DateTimeImmutable::createFromFormat(DATE_ATOM, $this->data[$offset]);
+                }
+
+                return null;
+            default:
+                return $this->data[$offset] ?? null;
+        }
+    }
+
+    /**
+     * get userfield by field name
+     *
+     * @param string $fieldName
+     *
+     * @return mixed|null
+     * @throws \Bitrix24\SDK\Services\CRM\Userfield\Exceptions\UserfieldNotFoundException
+     */
+    protected function getKeyWithUserfieldByFieldName(string $fieldName)
+    {
+        $fieldName = self::CRM_USERFIELD_PREFIX . $fieldName;
+        if (!$this->isKeyExists($fieldName)) {
+            throw new UserfieldNotFoundException(sprintf('crm userfield not found by field name %s', $fieldName));
+        }
+
+        return $this->$fieldName;
+    }
+}

src/Services/CRM/Contact/Result/ContactItemResult.php

@@ -4,59 +4,70 @@
 
 namespace Bitrix24\SDK\Services\CRM\Contact\Result;
 
-use Bitrix24\SDK\Core\Result\AbstractItem;
+use Bitrix24\SDK\Services\CRM\Common\Result\AbstractCrmItem;
+use DateTimeInterface;
 
 /**
  * Class ContactItemResult
  *
- * @property-read int    $ID
- * @property-read string $HONORIFIC
- * @property-read string $NAME
- * @property-read string $SECOND_NAME
- * @property-read string $LAST_NAME
- * @property-read string $PHOTO
- * @property-read string $BIRTHDATE
- * @property-read string $TYPE_ID
- * @property-read string $SOURCE_ID
- * @property-read string $SOURCE_DESCRIPTION
- * @property-read string $POST
- * @property-read string $ADDRESS
- * @property-read string $ADDRESS_2
- * @property-read string $ADDRESS_CITY
- * @property-read string $ADDRESS_POSTAL_CODE
- * @property-read string $ADDRESS_REGION
- * @property-read string $ADDRESS_PROVINCE
- * @property-read string $ADDRESS_COUNTRY
- * @property-read string $ADDRESS_COUNTRY_CODE
- * @property-read int    $ADDRESS_LOC_ADDR_ID
- * @property-read string $COMMENTS
- * @property-read string $OPENED
- * @property-read string $EXPORT
- * @property-read string $HAS_PHONE
- * @property-read string $HAS_EMAIL
- * @property-read string $HAS_IMOL
- * @property-read string $ASSIGNED_BY_ID
- * @property-read string $CREATED_BY_ID
- * @property-read string $MODIFY_BY_ID
- * @property-read string $DATE_CREATE
- * @property-read string $DATE_MODIFY
- * @property-read string $COMPANY_ID
- * @property-read string $COMPANY_IDS
- * @property-read string $LEAD_ID
- * @property-read string $ORIGINATOR_ID
- * @property-read string $ORIGIN_ID
- * @property-read string $ORIGIN_VERSION
- * @property-read int    $FACE_ID
- * @property-read string $UTM_SOURCE
- * @property-read string $UTM_MEDIUM
- * @property-read string $UTM_CAMPAIGN
- * @property-read string $UTM_CONTENT
- * @property-read string $UTM_TERM
- * @property-read string $PHONE
- * @property-read string $EMAIL
- * @property-read string $WEB
- * @property-read string $IM
+ * @property-read int                    $ID
+ * @property-read string                 $HONORIFIC
+ * @property-read string                 $NAME
+ * @property-read string                 $SECOND_NAME
+ * @property-read string                 $LAST_NAME
+ * @property-read string                 $PHOTO
+ * @property-read null|DateTimeInterface $BIRTHDATE
+ * @property-read string                 $TYPE_ID
+ * @property-read string                 $SOURCE_ID
+ * @property-read string                 $SOURCE_DESCRIPTION
+ * @property-read string                 $POST
+ * @property-read string                 $ADDRESS
+ * @property-read string                 $ADDRESS_2
+ * @property-read string                 $ADDRESS_CITY
+ * @property-read string                 $ADDRESS_POSTAL_CODE
+ * @property-read string                 $ADDRESS_REGION
+ * @property-read string                 $ADDRESS_PROVINCE
+ * @property-read string                 $ADDRESS_COUNTRY
+ * @property-read string                 $ADDRESS_COUNTRY_CODE
+ * @property-read int                    $ADDRESS_LOC_ADDR_ID
+ * @property-read string                 $COMMENTS
+ * @property-read string                 $OPENED
+ * @property-read bool                   $EXPORT
+ * @property-read string                 $HAS_PHONE
+ * @property-read string                 $HAS_EMAIL
+ * @property-read string                 $HAS_IMOL
+ * @property-read int                    $ASSIGNED_BY_ID
+ * @property-read int                    $CREATED_BY_ID
+ * @property-read int                    $MODIFY_BY_ID
+ * @property-read DateTimeInterface      $DATE_CREATE
+ * @property-read DateTimeInterface      $DATE_MODIFY
+ * @property-read string                 $COMPANY_ID
+ * @property-read string                 $COMPANY_IDS
+ * @property-read string                 $LEAD_ID
+ * @property-read string                 $ORIGINATOR_ID
+ * @property-read string                 $ORIGIN_ID
+ * @property-read string                 $ORIGIN_VERSION
+ * @property-read int                    $FACE_ID
+ * @property-read string                 $UTM_SOURCE
+ * @property-read string                 $UTM_MEDIUM
+ * @property-read string                 $UTM_CAMPAIGN
+ * @property-read string                 $UTM_CONTENT
+ * @property-read string                 $UTM_TERM
+ * @property-read string                 $PHONE
+ * @property-read string                 $EMAIL
+ * @property-read string                 $WEB
+ * @property-read string                 $IM
  */
-class ContactItemResult extends AbstractItem
+class ContactItemResult extends AbstractCrmItem
 {
+    /**
+     * @param string $userfieldName
+     *
+     * @return mixed|null
+     * @throws \Bitrix24\SDK\Services\CRM\Userfield\Exceptions\UserfieldNotFoundException
+     */
+    public function getUserfieldByFieldName(string $userfieldName)
+    {
+        return $this->getKeyWithUserfieldByFieldName($userfieldName);
+    }
 }

src/Services/CRM/Contact/Result/ContactUserfieldItemResult.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Contact\Result;
+
+use Bitrix24\SDK\Services\CRM\Userfield\Result\AbstractUserfieldItemResult;
+
+class ContactUserfieldItemResult extends AbstractUserfieldItemResult
+{
+}

src/Services/CRM/Contact/Result/ContactUserfieldResult.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Contact\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class ContactUserfieldResult extends AbstractResult
+{
+    /**
+     * @throws \Bitrix24\SDK\Core\Exceptions\BaseException
+     */
+    public function userfieldItem(): ContactUserfieldItemResult
+    {
+        return new ContactUserfieldItemResult($this->getCoreResponse()->getResponseData()->getResult()->getResultData());
+    }
+}