Feature/584 add catalog.storeproduct v3

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ### Added
 
+- Added service `Services\Catalog\StoreProduct` with support methods,
+  see [catalog.storeproduct.* methods](https://apidocs.bitrix24.com/api-reference/catalog/store-product/index.html) ([#584](https://github.com/bitrix24/b24phpsdk/issues/584)):
+    - `get` returns product stock information by record identifier
+    - `list` returns a list of product stock records by filter
+    - `getFields` returns the description of product stock fields
 - Added service `Services\Catalog\Document` with support methods,
   see [catalog.document.* methods](https://apidocs.bitrix24.com/api-reference/catalog/document/index.html) ([#559](https://github.com/bitrix24/b24phpsdk/issues/559)):
     - `add` creates a new warehouse accounting document, with batch calls support

Makefile

@@ -943,6 +943,10 @@ test-integration-catalog-document-element:
 test-integration-catalog-document-element-annotations:
 	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_catalog_document_element_annotations
 
+.PHONY: test-integration-catalog-store-product
+test-integration-catalog-store-product:
+	docker compose run --rm php-cli $(PHPUNIT) --testsuite integration_tests_catalog_store_product
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

docs/testing.md

@@ -302,6 +302,7 @@ skip_violations:
 | `make test-integration-catalog-document-annotations` | Warehouse accounting document result annotations |
 | `make test-integration-catalog-document-element` | Warehouse accounting document line items |
 | `make test-integration-catalog-document-element-annotations` | Warehouse accounting document line item result annotations |
+| `make test-integration-catalog-store-product` | Product stock by warehouse (`catalog.storeproduct.*`) |
 
 ### Tests — integration (Tasks)
 

phpunit.xml.dist

@@ -584,6 +584,9 @@
         <testsuite name="integration_tests_catalog_document_element_annotations">
             <file>./tests/Integration/Services/Catalog/DocumentElement/Result/DocumentElementItemResultTest.php</file>
         </testsuite>
+        <testsuite name="integration_tests_catalog_store_product">
+            <directory>./tests/Integration/Services/Catalog/StoreProduct/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

rector.php

@@ -100,7 +100,7 @@
     ->withSets(
         [
             LevelSetList::UP_TO_PHP_84,
-            PHPUnitSetList::PHPUNIT_110
+            PHPUnitSetList::ANNOTATIONS_TO_ATTRIBUTES
         ]
     )
     ->withImportNames(
@@ -142,7 +142,6 @@
         \Rector\Naming\Rector\Foreach_\RenameForeachValueVariableToMatchExprVariableRector::class,
         \Rector\Naming\Rector\Foreach_\RenameForeachValueVariableToMatchMethodCallReturnTypeRector::class,
         \Rector\Php83\Rector\ClassConst\AddTypeToConstRector::class,
-        \Rector\Php84\Rector\Class_\DeprecatedAnnotationToDeprecatedAttributeRector::class,
         \Rector\Php84\Rector\Foreach_\ForeachToArrayAnyRector::class,
         \Rector\Php84\Rector\Foreach_\ForeachToArrayFindRector::class,
         \Rector\Php84\Rector\MethodCall\NewMethodCallWithoutParenthesesRector::class,

src/Services/Catalog/CatalogServiceBuilder.php

@@ -290,4 +290,16 @@ public function documentElement(): Catalog\DocumentElement\Service\DocumentEleme
 
         return $this->serviceCache[__METHOD__];
     }
+
+    public function storeProduct(): Catalog\StoreProduct\Service\StoreProduct
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Catalog\StoreProduct\Service\StoreProduct(
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
 }

src/Services/Catalog/StoreProduct/Result/StoreProductFieldsResult.php

@@ -0,0 +1,29 @@
+<?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\StoreProduct\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class StoreProductFieldsResult extends AbstractResult
+{
+    /**
+     * @return array<string, array<string, mixed>>
+     * @throws BaseException
+     */
+    public function getFieldsDescription(): array
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult()['storeProduct'];
+    }
+}

src/Services/Catalog/StoreProduct/Result/StoreProductItemResult.php

@@ -0,0 +1,27 @@
+<?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\StoreProduct\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractAnnotatedItem;
+
+/**
+ * @property-read int        $id
+ * @property-read int        $productId
+ * @property-read int        $storeId
+ * @property-read float      $amount
+ * @property-read float|null $quantityReserved
+ */
+class StoreProductItemResult extends AbstractAnnotatedItem
+{
+}

src/Services/Catalog/StoreProduct/Result/StoreProductResult.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\StoreProduct\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class StoreProductResult extends AbstractResult
+{
+    public function storeProduct(): StoreProductItemResult
+    {
+        return new StoreProductItemResult(
+            $this->getCoreResponse()->getResponseData()->getResult()['storeProduct']
+        );
+    }
+}

src/Services/Catalog/StoreProduct/Result/StoreProductsResult.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\StoreProduct\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class StoreProductsResult extends AbstractResult
+{
+    /**
+     * @return StoreProductItemResult[]
+     * @throws BaseException
+     */
+    public function getStoreProducts(): array
+    {
+        $res = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult()['storeProducts'] as $item) {
+            $res[] = new StoreProductItemResult($item);
+        }
+
+        return $res;
+    }
+
+    /**
+     * @throws BaseException
+     */
+    public function getTotal(): int
+    {
+        return $this->getCoreResponse()->getResponseData()->getPagination()->getTotal() ?? 0;
+    }
+}

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

@@ -0,0 +1,92 @@
+<?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\StoreProduct\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\Services\AbstractService;
+use Bitrix24\SDK\Services\Catalog\StoreProduct\Result\StoreProductFieldsResult;
+use Bitrix24\SDK\Services\Catalog\StoreProduct\Result\StoreProductResult;
+use Bitrix24\SDK\Services\Catalog\StoreProduct\Result\StoreProductsResult;
+
+#[ApiServiceMetadata(new Scope(['catalog']))]
+class StoreProduct extends AbstractService
+{
+    /**
+     * Returns information about product stock by record identifier.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/catalog/store-product/catalog-store-product-get.html
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'catalog.storeproduct.get',
+        'https://apidocs.bitrix24.com/api-reference/catalog/store-product/catalog-store-product-get.html',
+        'Returns information about product stock by record identifier.'
+    )]
+    public function get(int $id): StoreProductResult
+    {
+        $this->guardPositiveId($id);
+
+        return new StoreProductResult($this->core->call('catalog.storeproduct.get', ['id' => $id]));
+    }
+
+    /**
+     * Returns a list of product stock records by filter.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/catalog/store-product/catalog-store-product-list.html
+     *
+     * @param string[]               $select
+     * @param array<string, mixed>   $filter
+     * @param array<string, string>  $order
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'catalog.storeproduct.list',
+        'https://apidocs.bitrix24.com/api-reference/catalog/store-product/catalog-store-product-list.html',
+        'Returns a list of product stock records by filter.'
+    )]
+    public function list(array $select = [], array $filter = [], array $order = []): StoreProductsResult
+    {
+        return new StoreProductsResult($this->core->call('catalog.storeproduct.list', [
+            'select' => $select,
+            'filter' => $filter,
+            'order' => $order,
+        ]));
+    }
+
+    /**
+     * Returns the fields of product stock records.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/catalog/store-product/catalog-store-product-get-fields.html
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'catalog.storeproduct.getFields',
+        'https://apidocs.bitrix24.com/api-reference/catalog/store-product/catalog-store-product-get-fields.html',
+        'Returns the fields of product stock records.'
+    )]
+    public function getFields(): StoreProductFieldsResult
+    {
+        return new StoreProductFieldsResult($this->core->call('catalog.storeproduct.getFields'));
+    }
+}

tests/Integration/Services/Catalog/StoreProduct/Result/StoreProductItemResultTest.php

@@ -0,0 +1,71 @@
+<?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\Tests\Integration\Services\Catalog\StoreProduct\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\TransportException;
+use Bitrix24\SDK\Services\Catalog\StoreProduct\Result\StoreProductItemResult;
+use Bitrix24\SDK\Services\Catalog\StoreProduct\Service\StoreProduct;
+use Bitrix24\SDK\Tests\CustomAssertions\CustomBitrix24Assertions;
+use Bitrix24\SDK\Tests\Integration\Factory;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(StoreProductItemResult::class)]
+class StoreProductItemResultTest extends TestCase
+{
+    use CustomBitrix24Assertions;
+
+    private StoreProduct $storeProductService;
+
+    /**
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[Test]
+    #[TestDox('all fields in StoreProductItemResult are annotated in phpdoc and match with raw api response')]
+    public function testAllFieldsAreAnnotated(): void
+    {
+        $rawItem = $this->storeProductService->list()->getCoreResponse()
+            ->getResponseData()->getResult()['storeProducts'][0];
+
+        $this->assertBitrix24AllResultItemFieldsAnnotated(
+            array_keys($rawItem),
+            StoreProductItemResult::class
+        );
+    }
+
+    /**
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[Test]
+    #[TestDox('all fields in StoreProductItemResult have valid type casting in magic getters')]
+    public function testAllFieldsHasValidTypeCastingInMagicGetters(): void
+    {
+        $item = $this->storeProductService->list()->getStoreProducts()[0];
+        $this->assertBitrix24ResultItemFieldsTypeCastMatchAnnotations(
+            $item,
+            StoreProductItemResult::class
+        );
+    }
+
+    #[\Override]
+    protected function setUp(): void
+    {
+        $this->storeProductService = Factory::getServiceBuilder()->getCatalogScope()->storeProduct();
+    }
+}