Expanded the product availability section (#3190)

* Expanded product availability
* Adapted to PHP 7,4

---------

Co-authored-by: Tomasz Dąbrowski <64841871+dabrt@users.noreply.github.com>

Author: mnocon

code_samples/api/product_catalog/src/Command/ProductCommand.php

@@ -2,6 +2,7 @@
 
 namespace App\Command;
 
+use App\ProductCatalog\Availability\PurchasableWithoutStockAvailabilityContext;
 use Ibexa\Contracts\Core\Repository\PermissionResolver;
 use Ibexa\Contracts\Core\Repository\UserService;
 use Ibexa\Contracts\ProductCatalog\Local\LocalProductServiceInterface;
@@ -84,26 +85,34 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         $product = $this->productService->getProduct('NEWMODIFIEDPRODUCT');
 
-        $productAvailabilityCreateStruct = new ProductAvailabilityCreateStruct($product, true, true);
+        $productAvailabilityCreateStruct = new ProductAvailabilityCreateStruct($product, false, true);
 
         $this->productAvailabilityService->createProductAvailability($productAvailabilityCreateStruct);
 
         if ($this->productAvailabilityService->hasAvailability($product)) {
             $availability = $this->productAvailabilityService->getAvailability($product);
 
-            $output->write($availability->isAvailable() ? 'Available' : 'Unavailable');
-            $output->writeln(' with stock ' . $availability->getStock());
-
-            $availability = $this->productAvailabilityService->getAvailability($product);
+            $output->writeln($availability->getAvailability() ? 'Available flag: true' : 'Available flag: false');
+            $output->writeln($availability->getComputedAvailability() ? 'Can be ordered: true' : 'Can be ordered: false');
+            $output->writeln('Stock: ' . $availability->getStock());
 
             $productAvailabilityUpdateStruct = new ProductAvailabilityUpdateStruct($product, true, false, 80);
 
             $this->productAvailabilityService->updateProductAvailability($productAvailabilityUpdateStruct);
 
-            $output->write($availability->isAvailable() ? 'Available' : 'Unavailable');
+            $output->writeln($availability->getAvailability() ? 'Available flag: true' : 'Available flag: false');
+            $output->writeln($availability->getComputedAvailability() ? 'Can be ordered: true' : 'Can be ordered: false');
             $output->writeln(' available now with stock ' . $availability->getStock());
         }
 
+        $availability = $this->productAvailabilityService->getAvailability(
+            $product,
+            new PurchasableWithoutStockAvailabilityContext()
+        );
+
+        $canBeOrdered = $availability->getComputedAvailability();
+        $output->writeln('Can be ordered: ' . ($canBeOrdered ? 'true' : 'false') . ', Stock: ' . $availability->getStock());
+
         $this->localProductService->deleteProduct($product);
 
         return self::SUCCESS;

code_samples/pim/availability/config/custom_services.yaml

@@ -0,0 +1,4 @@
+services:
+    App\ProductCatalog\Availability\ProductAvailabilityPurchasableWithoutStockStrategy:
+        tags:
+            - { name: ibexa.product_catalog.availability.strategy }

code_samples/pim/availability/src/ProductAvailabilityPurchasableWithoutStockStrategy.php

@@ -0,0 +1,70 @@
+<?php declare(strict_types=1);
+
+namespace App\ProductCatalog\Availability;
+
+use Ibexa\Contracts\ProductCatalog\ProductAvailabilityStrategyInterface;
+use Ibexa\Contracts\ProductCatalog\Values\Availability\AvailabilityContextInterface;
+use Ibexa\Contracts\ProductCatalog\Values\Availability\AvailabilityInterface;
+use Ibexa\Contracts\ProductCatalog\Values\ProductInterface;
+use Ibexa\ProductCatalog\Local\Persistence\Legacy\ProductAvailability\HandlerInterface;
+use Ibexa\ProductCatalog\Local\Repository\Values\Availability;
+
+final class ProductAvailabilityPurchasableWithoutStockStrategy implements ProductAvailabilityStrategyInterface
+{
+    private HandlerInterface $handler;
+
+    public function __construct(HandlerInterface $handler)
+    {
+        $this->handler = $handler;
+    }
+
+    public function accept(AvailabilityContextInterface $context): bool
+    {
+        return $context instanceof PurchasableWithoutStockAvailabilityContext;
+    }
+
+    public function getProductAvailability(
+        ProductInterface $product,
+        AvailabilityContextInterface $context
+    ): AvailabilityInterface {
+        $productAvailability = $this->handler->find($product->getCode());
+
+        $rawAvailableFlag = $productAvailability->isAvailable();
+        $stock = $productAvailability->getStock();
+        $isInfinite = $productAvailability->isInfinite();
+
+        $computedAvailable = $this->calculateAvailability(
+            $rawAvailableFlag,
+            $stock,
+            $isInfinite,
+        );
+
+        return new Availability(
+            $product,
+            $rawAvailableFlag,
+            $computedAvailable,
+            $isInfinite,
+            $stock,
+        );
+    }
+
+    private function calculateAvailability(
+        bool $rawAvailable,
+        ?int $stock,
+        bool $isInfinite
+    ): bool {
+        if ($rawAvailable === false) {
+            return false;
+        }
+
+        if ($isInfinite) {
+            return true;
+        }
+
+        if ($stock === null) {
+            return true;
+        }
+
+        return $stock >= 0;
+    }
+}

code_samples/pim/availability/src/PurchasableWithoutStockAvailabilityContext.php

@@ -0,0 +1,9 @@
+<?php declare(strict_types=1);
+
+namespace App\ProductCatalog\Availability;
+
+use Ibexa\Contracts\ProductCatalog\Values\Availability\AvailabilityContextInterface;
+
+final class PurchasableWithoutStockAvailabilityContext implements AvailabilityContextInterface
+{
+}

docs/product_catalog/create_custom_availability_strategy.md

@@ -0,0 +1,54 @@
+---
+description: Implement custom availability strategies to handle different business scenarios, for example pre-orders or per-region availability.
+---
+
+# Create custom availability strategy
+
+The product catalog uses an availability strategy to calculate [computed availability](products.md#availability-and-computed-availability) for a product.
+Computed availability decides whether the customers can order the product.
+The default availability strategy is based on the product availability and stock amount.
+
+You can replace this logic with a custom strategy to handle specific business scenarios, for example preorders, minimum order quantities, or per-region availability.
+
+The following example implements an availability strategy which allows buying products when they're set as available, without taking their stock into account.
+You could use it for [virtual products](products.md#product-types) or in preorder scenarios.
+
+## Create custom availability context
+
+Use an availability context to pass the parameters needed by the strategy to evaluate computed availability.
+To do it, create a class that implements the [`AvailabilityContextInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Availability-AvailabilityContextInterface.html) interface:
+
+``` php
+[[= include_file('code_samples/pim/availability/src/PurchasableWithoutStockAvailabilityContext.php') =]]
+```
+
+## Create custom availability strategy
+
+Create a class that implements the [`ProductAvailabilityStrategyInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-ProductAvailabilityStrategyInterface.html) interface:
+
+``` php
+[[= include_file('code_samples/pim/availability/src/ProductAvailabilityPurchasableWithoutStockStrategy.php') =]]
+```
+
+The strategy has two methods:
+
+- `accept()` decides if the strategy can handle the provided availability context
+- `getProductAvailability()` returns an [`AvailabilityInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Availability-AvailabilityInterface.html) object
+
+When constructing the `AvailabilityInterface` object, provide the stock amount, the availability flag, and the result of your custom availability logic.
+
+## Register strategy as a service
+
+If you're not using [autowiring]([[= symfony_doc =]]/service_container/autowiring.html), tag the strategy service with `ibexa.product_catalog.availability.strategy`:
+
+``` yaml
+[[= include_file('code_samples/pim/availability/config/custom_services.yaml') =]]
+```
+
+## Use custom context
+
+To evaluate product availability using a custom strategy, pass the custom context as the second argument to [`ProductAvailabilityServiceInterface::getAvailability()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-ProductAvailabilityServiceInterface.html):
+
+```php
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 122, 127, remove_indent=True) =]]
+```

docs/product_catalog/customize_product_catalog.md

@@ -14,4 +14,5 @@ You can customize various areas of the product catalog capabilities to adjust it
     "product_catalog/create_custom_name_schema_strategy",
     "product_catalog/customize_product_attribute_templates",
     "product_catalog/customize_product_embed_templates",
+    "product_catalog/create_custom_availability_strategy",
 ], columns=4) =]]

docs/product_catalog/product_api.md

@@ -1,5 +1,5 @@
 ---
-description: Use PHP API to manage products in PIM, their attributes, availability and prices.
+description: Use PHP API to manage products in PIM, their attributes, availability, and prices.
 month_change: false
 ---
 
@@ -23,15 +23,15 @@ month_change: false
 Get an individual product by using the `ProductServiceInterface::getProduct()` method:
 
 ``` php
-[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 55, 57, remove_indent=True) =]]
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 56, 58, remove_indent=True) =]]
 ```
 
 Find multiple products with `ProductServiceInterface::findProducts()`.
 
 Provide the method with optional filter, query or Sort Clauses.
 
 ``` php
-[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 59, 68, remove_indent=True) =]]
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 60, 69, remove_indent=True) =]]
 ```
 
 See [Product Search Criteria](product_search_criteria.md) and [Product Sort Clauses](product_sort_clauses.md) references for more information about how to use the [`ProductQuery`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Product-ProductQuery.html) class.
@@ -41,21 +41,21 @@ See [Product Search Criteria](product_search_criteria.md) and [Product Sort Clau
 To create, update and delete products, use the `LocalProductServiceInterface`.
 
 ``` php
-[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 80, 83, remove_indent=True) =]]
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 81, 84, remove_indent=True) =]]
 ```
 
 To create a product, use `LocalProductServiceInterface::newProductCreateStruct()` to get a [`ProductCreateStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Local-Values-Product-ProductCreateStruct.html).
 Provide the method with the product type object and the main language code.
 You also need to set (at least) the code for the product and the required Field of the underlying content type, `name`:
 
 ``` php
-[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 70, 76, remove_indent=True) =]]
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 71, 77, remove_indent=True) =]]
 ```
 
 To delete a product, use `LocalProductServiceInterface::deleteProduct()`:
 
 ``` php
-[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 107, 107, remove_indent=True) =]]
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 116, 116, remove_indent=True) =]]
 ```
 
 ### Product variants
@@ -214,17 +214,30 @@ You can also get a list of product types with `ProductTypeServiceInterface::find
 
 ## Product availability
 
-Product availability is an object which defines whether a product is available, and if so, in what stock.
+Product availability is an object which defines whether a product is set as available, in what stock, and whether it can be ordered.
 To manage it, use [`ProductAvailabilityServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-ProductAvailabilityServiceInterface.html).
 
-To check whether a product is available (with or without stock defined), use `ProductAvailabilityServiceInterface::hasAvailability()`.
+The [`AvailabilityInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Availability-AvailabilityInterface.html) provides two distinct availability values:
 
-Get the availability object with `ProductAvailabilityServiceInterface::getAvailability()`.
-You can then use `ProductAvailabilityServiceInterface::getStock()` to get the stock number for the product:
+- `getAvailability()` returns the value of availability flag as set for the product
+- `getComputedAvailability()` returns whether the product can be ordered
 
-```php
-[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 91, 95, remove_indent=True) =]]
-[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 105, 105, remove_indent=True) =]]
+For more information about the distinction between these two values, see [Availability and computed availability](products.md#availability-and-computed-availability).
+
+To check whether a product is set as available, use `ProductAvailabilityServiceInterface::hasAvailability()`.
+
+You can get the availability object with `ProductAvailabilityServiceInterface::getAvailability()`.
+The returned object contains both the stored and computed availability:
+
+``` php
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 92, 97, remove_indent=True) =]]
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 120, 120, remove_indent=True) =]]
+```
+
+To evaluate computed availability for a [specific context](create_custom_availability_strategy.md), for example, a specific requested quantity or customer group, pass an optional [`AvailabilityContextInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Availability-AvailabilityContextInterface.html) object as the second argument:
+
+``` php
+[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 108, 114, remove_indent=True) =]]
 ```
 
 To change availability for a product, use `ProductAvailabilityServiceInterface::updateProductAvailability()` with a [`ProductAvailabilityUpdateStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Availability-ProductAvailabilityUpdateStruct.html) and provide it with the product object.

docs/product_catalog/products.md

@@ -96,12 +96,24 @@ You set product availability per variant or per base product:
 - if a product cannot have variants (has no attributes with the "Used for product variants" flag), you set availability per base product
 - if a product can have variants (even if no variants are configured yet), you set availability per variant.
 
-When a product is available, it can have numerical stock defined.
+When a product is set as available, it can have numerical stock defined.
 The stock can also be set to infinite (for example, in case of digital products).
 
-!!! note
+### Availability and computed availability
 
-    Availability doesn't automatically mean that a product can be ordered.
-    A product can be available, but have zero stock.
+Setting a product as available doesn't automatically mean that it can be ordered.
+For example, a product can be set as available, but have zero stock.
 
-    A product can only be ordered when it has either positive stock, or stock set to infinite.
+The product catalog distinguishes between two types of availability:
+
+- Availability as a value set per product or variant
+
+    Availability represents whether the product was set as **Available**, for example in the [back office **Availability** tab]([[= user_doc =]]/product_catalog/manage_availability_and_stock/#set-product-availability) or [PHP API](product_api.md#product-availability).
+
+- Computed availability
+
+    Computed availability represents whether the product can actually be ordered.
+    By default, a product can only be ordered when it's set as available and has either positive or infinite stock.
+
+You can implement a custom strategy to handle different selling scenarios, such as minimum order quantity, minimum stock quantity, or region-specific availability.
+For more information, see [Create custom availability strategy](create_custom_availability_strategy.md).

docs/search/criteria_reference/productavailability_criterion.md

@@ -4,7 +4,12 @@ description: ProductAvailability Search Criterion
 
 # ProductAvailability Criterion
 
-The `ProductAvailability` Search Criterion searches for products by their availability.
+The `ProductAvailability` Search Criterion searches for products by the availability flag, the boolean value set per product or variant.
+
+To search for products that can be ordered, recreate the availability conditions with [existing product search criteria](product_search_criteria.md), for example [LogicalAnd](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Product-Query-Criterion-LogicalAnd.html), [LogicalOr](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-Product-Query-Criterion-LogicalOr.html), and [`ProductStock`](productstock_criterion.md).
+To recreate complex [custom availability strategies](create_custom_availability_strategy.md), you might need to implement [custom search criteria](search_criteria_and_sort_clauses.md#custom-criteria-and-sort-clauses) for the conditions not covered by the built-in ones.
+
+For more information, see [Availability and computed availability](products.md#availability-and-computed-availability).
 
 ## Arguments
 
@@ -43,4 +48,4 @@ $query = new ProductQuery(
             }
         }
     }
-    ```
+    ```

mkdocs.yml

@@ -386,12 +386,13 @@ nav:
         - Prices: product_catalog/prices.md
         - Price API: product_catalog/price_api.md
         - Customize product catalog:
-            - Customize product catalog: product_catalog/customize_product_catalog.md
             - Create custom attribute type: product_catalog/create_custom_attribute_type.md
-            - Create product code generator: product_catalog/create_product_code_generator.md
+            - Create custom availability strategy: product_catalog/create_custom_availability_strategy.md
             - Create custom catalog filter: product_catalog/create_custom_catalog_filter.md
             - Create custom name schema: product_catalog/create_custom_name_schema_strategy.md
+            - Create product code generator: product_catalog/create_product_code_generator.md
             - Customize product attribute templates: product_catalog/customize_product_attribute_templates.md
+            - Customize product catalog: product_catalog/customize_product_catalog.md
             - Customize product embed templates: product_catalog/customize_product_embed_templates.md
         - Add remote PIM support: product_catalog/add_remote_pim_support.md
     - Commerce: