Feature/495 add mailservice

.php-cs-fixer.php

@@ -29,6 +29,7 @@
     ->in(__DIR__ . '/src/Services/SonetGroup/')
     ->in(__DIR__ . '/src/Services/IMOpenLines/')
     ->in(__DIR__ . '/src/Services/Landing/')
+    ->in(__DIR__ . '/src/Services/MailService/')
     ->name('*.php')
     ->exclude(['vendor', 'storage', 'docker', 'docs']) // Exclude directories
     ->ignoreDotFiles(true)

CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ### Added
 
+- Added service `Services\MailService` with support for `mailservice.*` methods,
+  see [mailservice.* methods](https://apidocs.bitrix24.com/api-reference/mailservice/index.html) ([#495](https://github.com/bitrix24/b24phpsdk/issues/495)):
+    - `add` creates a new mail service (IMAP integration), with batch calls support
+    - `update` updates an existing mail service, with batch calls support
+    - `get` gets information about a mail service by its identifier
+    - `list` gets the list of active mail services, with batch calls support
+    - `delete` deletes a mail service, with batch calls support
+    - `fields` returns localized field labels of a mail service
+    - `count` counts active mail services
+
 - Added service `Services\Landing\Site\Service\Site` with support methods,
   see [landing.site.* methods](https://github.com/bitrix24/b24phpsdk/issues/267):
     - `add` adds a site

Makefile

@@ -69,7 +69,7 @@ help:
 	@echo "test-integration-landing-role - run Landing Role integration tests"
 	@echo "test-integration-landing-repowidget - run Landing RepoWidget integration tests"
 	@echo "test-integration-scope-landing-template - run Landing Template integration tests"
-
+	@echo "test-integration-mailservice - run MailService integration tests"
 
 .PHONY: docker-init
 docker-init:
@@ -492,6 +492,10 @@ test-integration-landing-role:
 test-integration-landing-repowidget:
 	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_landing_repowidget
 
+.PHONY: test-integration-mailservice
+test-integration-mailservice:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_mailservice
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

phpstan.neon.dist

@@ -37,6 +37,7 @@ parameters:
     - tests/Integration/Services/CRM/Documentgenerator/Document
     - tests/Integration/Services/CRM/Documentgenerator/Template
     - tests/Integration/Services/Landing
+    - tests/Integration/Services/MailService
   excludePaths:
     - tests/Integration/Services/CRM/Requisites/Service/RequisiteUserfieldUseCaseTest.php
     - tests/Integration/Services/CRM/Status

phpunit.xml.dist

@@ -262,6 +262,9 @@
         <testsuite name="integration_tests_landing_repowidget">
             <directory>./tests/Integration/Services/Landing/RepoWidget/</directory>
         </testsuite>
+        <testsuite name="integration_tests_mailservice">
+            <directory>./tests/Integration/Services/MailService/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

rector.php

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

src/Services/MailService/Batch.php

@@ -0,0 +1,108 @@
+<?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\MailService;
+
+use Bitrix24\SDK\Core\Contracts\CoreInterface;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+use Generator;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Custom Batch for MailService scope.
+ *
+ * Overrides updateEntityItems to pass ID as a top-level key (flat structure),
+ * matching the mailservice.update parameter format which does not use nested 'fields'.
+ *
+ * @see https://apidocs.bitrix24.com/api-reference/mailservice/mailservice-update.html
+ */
+class Batch extends \Bitrix24\SDK\Core\Batch
+{
+    public function __construct(CoreInterface $core, LoggerInterface $logger)
+    {
+        parent::__construct($core, $logger);
+    }
+
+    /**
+     * Update mail service items with batch call.
+     *
+     * Expects array structure:
+     * [
+     *   $mailServiceId => ['NAME' => '...', 'ACTIVE' => 'Y', ...],
+     *   ...
+     * ]
+     *
+     * @param array<int, array<string, mixed>> $entityItems
+     *
+     * @return Generator<int, ResponseData>
+     * @throws BaseException
+     */
+    #[\Override]
+    public function updateEntityItems(string $apiMethod, array $entityItems): Generator
+    {
+        $this->logger->debug(
+            'updateEntityItems.start',
+            [
+                'apiMethod' => $apiMethod,
+                'entityItems' => $entityItems,
+            ]
+        );
+
+        try {
+            $this->clearCommands();
+            foreach ($entityItems as $entityItemId => $entityItem) {
+                if (!is_int($entityItemId)) {
+                    throw new InvalidArgumentException(
+                        sprintf(
+                            'invalid type «%s» of mail service id «%s», the id must be integer type',
+                            gettype($entityItemId),
+                            $entityItemId
+                        )
+                    );
+                }
+
+                $entityItem['ID'] = $entityItemId;
+                $cmdArguments = $entityItem;
+
+                $this->registerCommand($apiMethod, $cmdArguments);
+            }
+
+            foreach ($this->getTraversable(true) as $cnt => $updatedItemResult) {
+                yield $cnt => $updatedItemResult;
+            }
+        } catch (InvalidArgumentException $exception) {
+            $errorMessage = sprintf('batch update entity items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+            throw $exception;
+        } catch (\Throwable $exception) {
+            $errorMessage = sprintf('batch update entity items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+
+            throw new BaseException($errorMessage, $exception->getCode(), $exception);
+        }
+
+        $this->logger->debug('updateEntityItems.finish');
+    }
+}

src/Services/MailService/MailServiceServiceBuilder.php

@@ -0,0 +1,40 @@
+<?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\MailService;
+
+use Bitrix24\SDK\Attributes\ApiServiceBuilderMetadata;
+use Bitrix24\SDK\Core\Credentials\Scope;
+use Bitrix24\SDK\Services\AbstractServiceBuilder;
+use Bitrix24\SDK\Services\MailService;
+
+#[ApiServiceBuilderMetadata(new Scope(['mailservice']))]
+class MailServiceServiceBuilder extends AbstractServiceBuilder
+{
+    public function mailService(): MailService\Service\MailService
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $batch = new MailService\Batch(
+                $this->core,
+                $this->log
+            );
+            $this->serviceCache[__METHOD__] = new MailService\Service\MailService(
+                new MailService\Service\Batch($batch, $this->log),
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
+}

src/Services/MailService/Result/MailServiceItemResult.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\MailService\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+
+/**
+ * Mail service item result.
+ *
+ * @property-read int $ID
+ * @property-read string $SITE_ID
+ * @property-read bool $ACTIVE
+ * @property-read int $SORT
+ * @property-read string $NAME
+ * @property-read string $SERVER
+ * @property-read int|null $PORT
+ * @property-read bool $ENCRYPTION
+ * @property-read string $LINK
+ * @property-read string|null $ICON
+ * @property-read string|null $SMTP_SERVER
+ * @property-read int|null $SMTP_PORT
+ * @property-read bool $SMTP_LOGIN_AS_IMAP
+ * @property-read bool $SMTP_PASSWORD_AS_IMAP
+ * @property-read bool|null $SMTP_ENCRYPTION
+ * @property-read bool|null $UPLOAD_OUTGOING
+ */
+class MailServiceItemResult extends AbstractItem
+{
+    public function __get($offset)
+    {
+        return match ($offset) {
+            'ID', 'SORT', 'PORT', 'SMTP_PORT' => isset($this->data[$offset]) ? (int)$this->data[$offset] : null,
+            'ACTIVE', 'ENCRYPTION', 'SMTP_LOGIN_AS_IMAP', 'SMTP_PASSWORD_AS_IMAP' => $this->data[$offset] === 'Y',
+            'SMTP_ENCRYPTION', 'UPLOAD_OUTGOING' => isset($this->data[$offset]) ? $this->data[$offset] === 'Y' : null,
+            default => $this->data[$offset] ?? null,
+        };
+    }
+}

src/Services/MailService/Result/MailServiceResult.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\MailService\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Single mail service result for mailservice.get.
+ *
+ * @see https://apidocs.bitrix24.com/api-reference/mailservice/mailservice-get.html
+ */
+class MailServiceResult extends AbstractResult
+{
+    /**
+     * Get mail service item.
+     */
+    public function mailService(): MailServiceItemResult
+    {
+        return new MailServiceItemResult($this->getCoreResponse()->getResponseData()->getResult());
+    }
+}

src/Services/MailService/Result/MailServicesResult.php

@@ -0,0 +1,41 @@
+<?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\MailService\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Mail services list result for mailservice.list.
+ *
+ * @see https://apidocs.bitrix24.com/api-reference/mailservice/mailservice-list.html
+ */
+class MailServicesResult extends AbstractResult
+{
+    /**
+     * Get mail service items.
+     *
+     * @return MailServiceItemResult[]
+     * @throws BaseException
+     */
+    public function getMailServices(): array
+    {
+        $items = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult() as $item) {
+            $items[] = new MailServiceItemResult($item);
+        }
+
+        return $items;
+    }
+}