231 contact userfields

CHANGELOG.md

@@ -1,16 +1,24 @@
 # 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
+* add method getUserfieldByFieldName for `ContactItemResult`
+* 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

@@ -86,6 +86,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 +140,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,65 @@
+<?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 унести в отдельный класс и покрыть тестами
+        switch ($offset) {
+            case 'ID':
+            case 'ASSIGNED_BY_ID':
+            case 'CREATED_BY_ID':
+            case 'MODIFY_BY_ID':
+                return (int)$this->data[$offset];
+            case 'EXPORT':
+            case 'HAS_PHONE':
+            case 'HAS_EMAIL':
+            case 'HAS_IMOL':
+            case 'OPENED':
+                return $this->data[$offset] === 'Y';
+            case 'DATE_CREATE':
+            case 'DATE_MODIFY':
+            case 'BIRTHDATE':
+                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());
+    }
+}

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

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\CRM\Contact\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class ContactUserfieldsResult extends AbstractResult
+{
+    /**
+     * @return ContactUserfieldItemResult[]
+     * @throws BaseException
+     */
+    public function getUserfields(): array
+    {
+        $res = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult()->getResultData() as $item) {
+            $res[] = new ContactUserfieldItemResult($item);
+        }
+
+        return $res;
+    }
+}

src/Services/CRM/Contact/Service/Contact.php

@@ -360,7 +360,7 @@ public function list(array $order, array $filter, array $select, int $start): Co
      * @throws BaseException
      * @throws TransportException
      */
-    public function update(int $contactId, array $fields, array $params): UpdatedItemResult
+    public function update(int $contactId, array $fields, array $params = []): UpdatedItemResult
     {
         return new UpdatedItemResult(
             $this->core->call(