Unify filters

bin/hook-docs/data/actions.json

@@ -31,7 +31,7 @@
                         "types": [
                             "integer"
                         ],
-                        "variable": "$quantity"
+                        "variable": "$request_quantity"
                     },
                     {
                         "name": "param",

bin/hook-docs/data/filters.json

@@ -939,40 +939,49 @@
             "args": 2
         },
         {
-            "name": "woocommerce_store_api_{$type}_quantity_{$value_type}",
+            "name": "woocommerce_store_api_product_quantity_{$value_type}",
             "file": "StoreApi/Utilities/QuantityLimits.php",
             "type": "filter",
             "doc": {
                 "description": "Filters the quantity minimum for a cart item in Store API. This allows extensions to control the minimum qty of items already within the cart.",
-                "long_description": "Hook name will reflect the product or cart item depending on what is provided, so either:  - woocommerce_store_api_product_quantity_minimum  - woocommerce_store_api_cart_item_quantity_minimum",
+                "long_description": "The suffix of the hook will vary depending on the value being filtered. For example, minimum, maximum, multiple_of, editable.",
                 "tags": [
                     {
                         "name": "param",
-                        "content": "Minimum qty which defaults to 1.",
+                        "content": "The value being filtered.",
                         "types": [
-                            "integer"
+                            "mixed"
                         ],
-                        "variable": "$minimum"
+                        "variable": "$value"
                     },
                     {
                         "name": "param",
-                        "content": "Product or cart item being added/updated in the cart.",
+                        "content": "The product object.",
                         "types": [
-                            "array"
+                            "\\WC_Product"
                         ],
-                        "variable": "$cart_item_or_product"
+                        "variable": "$product"
+                    },
+                    {
+                        "name": "param",
+                        "content": "The cart item if the product exists in the cart, or null.",
+                        "types": [
+                            "array",
+                            "null"
+                        ],
+                        "variable": "$cart_item"
                     },
                     {
                         "name": "return",
                         "content": "",
                         "types": [
-                            "integer"
+                            "mixed"
                         ]
                     }
                 ],
-                "long_description_html": "<p>Hook name will reflect the product or cart item depending on what is provided, so either:</p> <ul> <li>woocommerce_store_api_product_quantity_minimum</li> <li>woocommerce_store_api_cart_item_quantity_minimum</li> </ul>"
+                "long_description_html": "<p>The suffix of the hook will vary depending on the value being filtered. For example, minimum, maximum, multiple_of, editable.</p>"
             },
-            "args": 2
+            "args": 3
         },
         {
             "name": "woocommerce_variation_option_name",

docs/extensibility/actions.md

@@ -47,7 +47,7 @@
 Fires when an item is added to the cart.
 
 ```php
-do_action( 'woocommerce_add_to_cart', string $cart_id, integer $product_id, integer $quantity, integer $variation_id, array $variation, array $cart_item_data )
+do_action( 'woocommerce_add_to_cart', string $cart_id, integer $product_id, integer $request_quantity, integer $variation_id, array $variation, array $cart_item_data )
 ```
 
 ### Description
@@ -60,7 +60,7 @@ do_action( 'woocommerce_add_to_cart', string $cart_id, integer $product_id, inte
 | -------- | ---- | ----------- |
 | $cart_id | string | ID of the item in the cart. |
 | $product_id | integer | ID of the product added to the cart. |
-| $quantity | integer | Quantity of the item added to the cart. |
+| $request_quantity | integer | Quantity of the item added to the cart. |
 | $variation_id | integer | Variation ID of the product added to the cart. |
 | $variation | array | Array of variation data. |
 | $cart_item_data | array | Array of other cart item data. |

docs/extensibility/filters.md

@@ -33,7 +33,7 @@
  - [woocommerce_show_page_title](#woocommerce_show_page_title)
  - [woocommerce_store_api_disable_nonce_check](#woocommerce_store_api_disable_nonce_check)
  - [woocommerce_store_api_product_quantity_limit](#woocommerce_store_api_product_quantity_limit)
- - [woocommerce_store_api_{$type}_quantity_{$value_type}](#woocommerce_store_api_-type-_quantity_-value_type)
+ - [woocommerce_store_api_product_quantity_{$value_type}](#woocommerce_store_api_product_quantity_-value_type)
  - [woocommerce_variation_option_name](#woocommerce_variation_option_name)
 
 ---
@@ -814,30 +814,31 @@ File: [StoreApi/Utilities/QuantityLimits.php](../src/StoreApi/Utilities/Quantity
 
 ---
 
-## woocommerce_store_api_{$type}_quantity_{$value_type}
+## woocommerce_store_api_product_quantity_{$value_type}
 
 
 Filters the quantity minimum for a cart item in Store API. This allows extensions to control the minimum qty of items already within the cart.
 
 ```php
-apply_filters( 'woocommerce_store_api_{$type}_quantity_{$value_type}', integer $minimum, array $cart_item_or_product )
+apply_filters( 'woocommerce_store_api_product_quantity_{$value_type}', mixed $value, \WC_Product $product, array|null $cart_item )
 ```
 
 ### Description
 
-<p>Hook name will reflect the product or cart item depending on what is provided, so either:</p> <ul> <li>woocommerce_store_api_product_quantity_minimum</li> <li>woocommerce_store_api_cart_item_quantity_minimum</li> </ul>
+<p>The suffix of the hook will vary depending on the value being filtered. For example, minimum, maximum, multiple_of, editable.</p>
 
 ### Parameters
 
 | Argument | Type | Description |
 | -------- | ---- | ----------- |
-| $minimum | integer | Minimum qty which defaults to 1. |
-| $cart_item_or_product | array | Product or cart item being added/updated in the cart. |
+| $value | mixed | The value being filtered. |
+| $product | \WC_Product | The product object. |
+| $cart_item | array, null | The cart item if the product exists in the cart, or null. |
 
 ### Returns
 
 
-`integer` 
+`mixed` 
 
 ### Source
 

src/StoreApi/Schemas/CartItemSchema.php

@@ -341,7 +341,7 @@ public function get_item_response( $cart_item ) {
 			'key'                  => $cart_item['key'],
 			'id'                   => $product->get_id(),
 			'quantity'             => wc_stock_amount( $cart_item['quantity'] ),
-			'quantity_limits'      => (object) ( new QuantityLimits() )->get_quantity_limits( $cart_item ),
+			'quantity_limits'      => (object) ( new QuantityLimits() )->get_cart_item_quantity_limits( $cart_item ),
 			'name'                 => $this->prepare_html_response( $product->get_title() ),
 			'short_description'    => $this->prepare_html_response( wc_format_content( wp_kses_post( $product->get_short_description() ) ) ),
 			'description'          => $this->prepare_html_response( wc_format_content( wp_kses_post( $product->get_description() ) ) ),

src/StoreApi/Utilities/QuantityLimits.php

@@ -21,7 +21,7 @@ final class QuantityLimits {
 	 * @param array $cart_item A cart item array.
 	 * @return array
 	 */
-	public function get_quantity_limits( $cart_item ) {
+	public function get_cart_item_quantity_limits( $cart_item ) {
 		$product = $cart_item['data'] ?? false;
 
 		if ( ! $product instanceof \WC_Product ) {
@@ -88,7 +88,7 @@ public function limit_to_multiple( int $number, int $multiple_of, string $roundi
 	 * @return \WP_Error|true
 	 */
 	public function validate_cart_item_quantity( $quantity, $cart_item ) {
-		$limits = $this->get_quantity_limits( $cart_item );
+		$limits = $this->get_cart_item_quantity_limits( $cart_item );
 
 		if ( ! $limits['editable'] ) {
 			return new \WP_Error(
@@ -191,19 +191,21 @@ protected function get_remaining_stock( \WC_Product $product ) {
 	 * @return mixed
 	 */
 	protected function filter_value( $value, string $value_type, $cart_item_or_product ) {
-		$type = $cart_item_or_product instanceof \WC_Product ? 'product' : 'cart_item';
+		$is_product = $cart_item_or_product instanceof \WC_Product;
+		$product    = $is_product ? $cart_item_or_product : $cart_item_or_product['data'];
+		$cart_item  = $is_product ? null : $cart_item_or_product;
 		/**
 		 * Filters the quantity minimum for a cart item in Store API. This allows extensions to control the minimum qty
 		 * of items already within the cart.
 		 *
-		 * Hook name will reflect the product or cart item depending on what is provided, so either:
-		 *  - woocommerce_store_api_product_quantity_minimum
-		 *  - woocommerce_store_api_cart_item_quantity_minimum
+		 * The suffix of the hook will vary depending on the value being filtered.
+		 * For example, minimum, maximum, multiple_of, editable.
 		 *
-		 * @param integer $minimum Minimum qty which defaults to 1.
-		 * @param array $cart_item_or_product Product or cart item being added/updated in the cart.
-		 * @return integer
+		 * @param mixed $value The value being filtered.
+		 * @param \WC_Product $product The product object.
+		 * @param array|null $cart_item The cart item if the product exists in the cart, or null.
+		 * @return mixed
 		 */
-		return apply_filters( "woocommerce_store_api_{$type}_quantity_{$value_type}", $value, $cart_item_or_product );
+		return apply_filters( "woocommerce_store_api_product_quantity_{$value_type}", $value, $product, $cart_item );
 	}
 }