Feature/484 add timeman

CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ### Added
 
+- Added `Services\Timeman` service with support for workday tracking methods,
+  see [timeman.* methods](https://apidocs.bitrix24.com/api-reference/timeman/index.html):
+    - `open` — starts a new workday or continues after pause/close
+    - `pause` — pauses the current workday
+    - `close` — closes the current workday
+    - `status` — gets current workday status
+    - `settings` — gets user's work time settings
+      ([#484](https://github.com/bitrix24/b24phpsdk/issues/484))
 - Added support for events:
     - `onCrmDocumentGeneratorDocumentAdd` — fires when a document is created,
       see [event documentation](https://apidocs.bitrix24.com/api-reference/crm/document-generator/documents/events/on-crm-document-generator-document-add.html)

Makefile

@@ -445,6 +445,10 @@ integration_tests_crm_documentgenerator_document:
 integration_tests_crm_documentgenerator_template:
 	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_crm_documentgenerator_template
 
+.PHONY: test-integration-scope-timeman
+test-integration-scope-timeman:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_scope_timeman
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

phpstan.neon.dist

@@ -36,6 +36,7 @@ parameters:
     - tests/Integration/Services/CRM/Documentgenerator/Numerator
     - tests/Integration/Services/CRM/Documentgenerator/Document
     - tests/Integration/Services/CRM/Documentgenerator/Template
+    - tests/Integration/Services/Timeman
   excludePaths:
     - tests/Integration/Services/CRM/Requisites/Service/RequisiteUserfieldUseCaseTest.php
     - tests/Integration/Services/CRM/Status

phpunit.xml.dist

@@ -232,6 +232,9 @@
         <testsuite name="integration_tests_scope_sonet_group">
             <directory>./tests/Integration/Services/SonetGroup/</directory>
         </testsuite>
+        <testsuite name="integration_tests_scope_timeman">
+            <directory>./tests/Integration/Services/Timeman/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

rector.php

@@ -77,6 +77,8 @@
         __DIR__ . '/src/Services/CRM/Documentgenerator/Template',
         __DIR__ . '/tests/Integration/Services/CRM/Documentgenerator/Template',
         __DIR__ . '/tests/Unit/',
+        __DIR__ . '/src/Services/Timeman',
+        __DIR__ . '/tests/Integration/Services/Timeman',
     ])
     ->withCache(cacheDirectory: __DIR__ . '/var/.cache/rector')
     ->withSets(

src/Services/ServiceBuilder.php

@@ -36,6 +36,7 @@
 use Bitrix24\SDK\Services\Calendar\CalendarServiceBuilder;
 use Bitrix24\SDK\Services\Paysystem\PaysystemServiceBuilder;
 use Bitrix24\SDK\Services\SonetGroup\SonetGroupServiceBuilder;
+use Bitrix24\SDK\Services\Timeman\TimemanServiceBuilder;
 use Psr\Log\LoggerInterface;
 
 class ServiceBuilder extends AbstractServiceBuilder
@@ -334,5 +335,18 @@ public function getSonetGroupScope(): SonetGroupServiceBuilder
 
         return $this->serviceCache[__METHOD__];
     }
-
+
+    public function getTimemanScope(): TimemanServiceBuilder
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new TimemanServiceBuilder(
+                $this->core,
+                $this->batch,
+                $this->bulkItemsReader,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
 }

src/Services/Timeman/Result/TimemanSettingsItemResult.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Timeman\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+
+/**
+ * Represents a single settings item returned by timeman.settings method.
+ *
+ * @property-read bool $UF_TIMEMAN
+ * @property-read bool $UF_TM_FREE
+ * @property-read string $UF_TM_MAX_START
+ * @property-read string $UF_TM_MIN_FINISH
+ * @property-read string $UF_TM_MIN_DURATION
+ * @property-read string $UF_TM_ALLOWED_DELTA
+ * @property-read bool|null $ADMIN
+ */
+class TimemanSettingsItemResult extends AbstractItem
+{
+}
+

src/Services/Timeman/Result/TimemanSettingsResult.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Timeman\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Result wrapping the settings object returned by timeman.settings.
+ */
+class TimemanSettingsResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function getSettings(): TimemanSettingsItemResult
+    {
+        return new TimemanSettingsItemResult($this->getCoreResponse()->getResponseData()->getResult());
+    }
+}
+

src/Services/Timeman/Result/WorkdayItemResult.php

@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Timeman\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+use Carbon\CarbonImmutable;
+
+/**
+ * Represents a single workday item returned by timeman.open, timeman.pause, timeman.close, timeman.status methods.
+ *
+ * @property-read string $STATUS
+ * @property-read CarbonImmutable|null $TIME_START
+ * @property-read CarbonImmutable|null $TIME_FINISH
+ * @property-read string $DURATION
+ * @property-read string $TIME_LEAKS
+ * @property-read bool $ACTIVE
+ * @property-read string $IP_OPEN
+ * @property-read string|null $IP_CLOSE
+ * @property-read float $LAT_OPEN
+ * @property-read float $LON_OPEN
+ * @property-read float $LAT_CLOSE
+ * @property-read float $LON_CLOSE
+ * @property-read int $TZ_OFFSET
+ */
+class WorkdayItemResult extends AbstractItem
+{
+    public function __get($offset)
+    {
+        return match ($offset) {
+            'TIME_START', 'TIME_FINISH' => isset($this->data[$offset])
+                ? CarbonImmutable::createFromFormat(DATE_ATOM, $this->data[$offset])
+                : null,
+            'TZ_OFFSET' => isset($this->data[$offset]) ? (int)$this->data[$offset] : null,
+            'LAT_OPEN', 'LON_OPEN', 'LAT_CLOSE', 'LON_CLOSE' => isset($this->data[$offset]) ? (float)$this->data[$offset] : null,
+            default => $this->data[$offset] ?? null,
+        };
+    }
+}

src/Services/Timeman/Result/WorkdayResult.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@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\Timeman\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Result wrapping a single workday object returned by timeman.open, timeman.pause, timeman.close, timeman.status.
+ */
+class WorkdayResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function getWorkday(): WorkdayItemResult
+    {
+        return new WorkdayItemResult($this->getCoreResponse()->getResponseData()->getResult());
+    }
+}
+