Feature/570 add catalog.ratio

.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/Catalog/')
     ->name('*.php')
     ->exclude(['vendor', 'storage', 'docker', 'docs']) // Exclude directories
     ->ignoreDotFiles(true)

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ### Added
 
+- Added service `Services\Catalog\Ratio` with support methods,
+  see [catalog.ratio.* methods](https://apidocs.bitrix24.com/api-reference/catalog/ratio/index.html) ([#570](https://github.com/bitrix24/b24phpsdk/issues/570)):
+    - `get` gets the values of a measurement unit ratio by identifier
+    - `list` gets the list of measurement unit ratios matching a filter
+    - `getFields` returns the description of measurement unit ratio fields
 - 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

@@ -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-catalog-ratio
+test-integration-catalog-ratio:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_catalog_ratio
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

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_catalog_ratio">
+            <directory>./tests/Integration/Services/Catalog/Ratio/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

src/Services/Catalog/Catalog/Result/CatalogItemResult.php

@@ -29,4 +29,4 @@
  */
 class CatalogItemResult extends AbstractCatalogItem
 {
-}
+}

src/Services/Catalog/Catalog/Result/CatalogResult.php

@@ -21,4 +21,4 @@ public function catalog(): CatalogItemResult
     {
         return new CatalogItemResult($this->getCoreResponse()->getResponseData()->getResult()['catalog']);
     }
-}
+}

src/Services/Catalog/Catalog/Result/CatalogsResult.php

@@ -32,4 +32,4 @@ public function getCatalogs(): array
 
         return $res;
     }
-}
+}

src/Services/Catalog/Catalog/Service/Catalog.php

@@ -82,4 +82,4 @@ public function fields(): FieldsResult
     {
         return new FieldsResult($this->core->call('catalog.catalog.getFields'));
     }
-}
+}

src/Services/Catalog/CatalogServiceBuilder.php

@@ -17,6 +17,7 @@
 use Bitrix24\SDK\Core\Credentials\Scope;
 use Bitrix24\SDK\Services\AbstractServiceBuilder;
 use Bitrix24\SDK\Services\Catalog;
+
 #[ApiServiceBuilderMetadata(new Scope(['catalog']))]
 class CatalogServiceBuilder extends AbstractServiceBuilder
 {
@@ -44,4 +45,16 @@ public function catalog(): Catalog\Catalog\Service\Catalog
 
         return $this->serviceCache[__METHOD__];
     }
-}
+
+    public function ratio(): Catalog\Ratio\Service\Ratio
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Catalog\Ratio\Service\Ratio(
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
+}

src/Services/Catalog/Common/ProductType.php

@@ -20,4 +20,4 @@ enum ProductType: int
     case SKU = 3;
     case productOffer = 4;
     case genericOffer = 5;
-}
+}

src/Services/Catalog/Common/Result/AbstractCatalogItem.php

@@ -109,4 +109,4 @@ protected function getKeyWithUserfieldByFieldName(string $fieldName)
 
         return $this->$fieldName;
     }
-}
+}

src/Services/Catalog/Product/Result/ProductItemResult.php

@@ -52,4 +52,4 @@
  */
 class ProductItemResult extends AbstractCatalogItem
 {
-}
+}

src/Services/Catalog/Product/Result/ProductResult.php

@@ -26,4 +26,4 @@ public function product(): ProductItemResult
 
         return new ProductItemResult($this->getCoreResponse()->getResponseData()->getResult()['product']);
     }
-}
+}

src/Services/Catalog/Product/Result/ProductsResult.php

@@ -31,4 +31,4 @@ public function getProducts(): array
 
         return $res;
     }
-}
+}

src/Services/Catalog/Product/Service/Batch.php

@@ -25,7 +25,7 @@
 {
     public function __construct(
         protected BatchOperationsInterface $batch,
-        protected LoggerInterface          $log)
-    {
+        protected LoggerInterface          $log
+    ) {
     }
-}
+}

src/Services/Catalog/Product/Service/Product.php

@@ -25,7 +25,6 @@
 use Bitrix24\SDK\Services\Catalog\Common\ProductType;
 use Bitrix24\SDK\Services\Catalog\Product\Result\ProductResult;
 use Bitrix24\SDK\Services\Catalog\Product\Result\ProductsResult;
-
 use Psr\Log\LoggerInterface;
 
 #[ApiServiceMetadata(new Scope(['catalog']))]
@@ -35,8 +34,7 @@ public function __construct(
         public Batch           $batch,
         CoreInterface   $core,
         LoggerInterface $logger
-    )
-    {
+    ) {
         parent::__construct($core, $logger);
     }
 
@@ -71,7 +69,9 @@ public function get(int $productId): ProductResult
     )]
     public function add(array $productFields): ProductResult
     {
-        return new ProductResult($this->core->call('catalog.product.add', [
+        return new ProductResult($this->core->call(
+            'catalog.product.add',
+            [
                 'fields' => $productFields
             ]
         ));
@@ -140,4 +140,4 @@ public function fieldsByFilter(int $iblockId, ProductType $productType, ?array $
 
         return new FieldsResult($this->core->call('catalog.product.getFieldsByFilter', ['filter' => $filter]));
     }
-}
+}

src/Services/Catalog/Ratio/Result/RatioItemResult.php

@@ -0,0 +1,26 @@
+<?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\Catalog\Ratio\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+
+/**
+ * @property-read int   $id
+ * @property-read bool  $isDefault
+ * @property-read int   $productId
+ * @property-read float $ratio
+ */
+class RatioItemResult extends AbstractItem
+{
+}

src/Services/Catalog/Ratio/Result/RatioResult.php

@@ -0,0 +1,28 @@
+<?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\Catalog\Ratio\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class RatioResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function ratio(): RatioItemResult
+    {
+        return new RatioItemResult($this->getCoreResponse()->getResponseData()->getResult()['ratio']);
+    }
+}

src/Services/Catalog/Ratio/Result/RatiosResult.php

@@ -0,0 +1,42 @@
+<?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\Catalog\Ratio\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class RatiosResult extends AbstractResult
+{
+    /**
+     * @return RatioItemResult[]
+     * @throws BaseException
+     */
+    public function getRatios(): array
+    {
+        $items = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult()['ratios'] as $item) {
+            $items[] = new RatioItemResult($item);
+        }
+
+        return $items;
+    }
+
+    /**
+     * @throws BaseException
+     */
+    public function getTotal(): int
+    {
+        return $this->getCoreResponse()->getResponseData()->getPagination()->getTotal() ?? 0;
+    }
+}

src/Services/Catalog/Ratio/Service/Ratio.php

@@ -0,0 +1,88 @@
+<?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\Catalog\Ratio\Service;
+
+use Bitrix24\SDK\Attributes\ApiEndpointMetadata;
+use Bitrix24\SDK\Attributes\ApiServiceMetadata;
+use Bitrix24\SDK\Core\Credentials\Scope;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\TransportException;
+use Bitrix24\SDK\Core\Result\FieldsResult;
+use Bitrix24\SDK\Services\AbstractService;
+use Bitrix24\SDK\Services\Catalog\Ratio\Result\RatioResult;
+use Bitrix24\SDK\Services\Catalog\Ratio\Result\RatiosResult;
+
+#[ApiServiceMetadata(new Scope(['catalog']))]
+class Ratio extends AbstractService
+{
+    /**
+     * Returns the values of the measurement unit ratio fields by identifier.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/catalog/ratio/catalog-ratio-get.html
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'catalog.ratio.get',
+        'https://apidocs.bitrix24.com/api-reference/catalog/ratio/catalog-ratio-get.html',
+        'Returns the values of the measurement unit ratio fields by identifier.'
+    )]
+    public function get(int $id): RatioResult
+    {
+        $this->guardPositiveId($id);
+
+        return new RatioResult($this->core->call('catalog.ratio.get', ['id' => $id]));
+    }
+
+    /**
+     * Returns a list of measurement unit ratios from the catalog matching the given filter.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/catalog/ratio/catalog-ratio-list.html
+     *
+     * @param string[]             $select
+     * @param array<string, mixed> $filter
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'catalog.ratio.list',
+        'https://apidocs.bitrix24.com/api-reference/catalog/ratio/catalog-ratio-list.html',
+        'Returns a list of measurement unit ratios from the catalog matching the given filter.'
+    )]
+    public function list(array $select = [], array $filter = []): RatiosResult
+    {
+        return new RatiosResult($this->core->call('catalog.ratio.list', [
+            'select' => $select,
+            'filter' => $filter,
+        ]));
+    }
+
+    /**
+     * Returns the available fields of a measurement unit ratio.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/catalog/ratio/catalog-ratio-get-fields.html
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'catalog.ratio.getFields',
+        'https://apidocs.bitrix24.com/api-reference/catalog/ratio/catalog-ratio-get-fields.html',
+        'Returns the available fields of a measurement unit ratio.'
+    )]
+    public function fields(): FieldsResult
+    {
+        return new FieldsResult($this->core->call('catalog.ratio.getFields'));
+    }
+}

tests/CustomAssertions/CustomBitrix24Assertions.php

@@ -22,9 +22,10 @@
 use Carbon\CarbonImmutable;
 use MoneyPHP\Percentage\Percentage;
 use Typhoon\Reflection\TyphoonReflector;
-use function Typhoon\Type\stringify;
 use Money\Currency;
 
+use function Typhoon\Type\stringify;
+
 trait CustomBitrix24Assertions
 {
     /**
@@ -225,6 +226,20 @@ protected function assertBitrix24AllResultItemFieldsHasValidTypeAnnotation(
                         );
                         break;
                     }
+                    if (str_contains(mb_strtoupper($fieldCode), 'RATIO')) {
+                        $this->assertTrue(
+                            str_contains($propsFromAnnotations[$fieldCode], 'float'),
+                            sprintf(
+                                'class «%s» field «%s» has invalid type phpdoc annotation «%s», field type from bitrix24 is «%s», expected sdk-type «%s»',
+                                $resultItemClassName,
+                                $fieldCode,
+                                $propsFromAnnotations[$fieldCode],
+                                $fieldData['type'],
+                                'float'
+                            )
+                        );
+                        break;
+                    }
                     $this->assertTrue(
                         str_contains($propsFromAnnotations[$fieldCode], 'Money\Money'),
                         sprintf(