# Extension Hooks

All hook names follow the `woocommerce_globale_pro_` prefix convention. Each constant is defined on the class that fires or consumes the hook, so it is safe to reference constants rather than raw strings.

Example implementations are provided in the plugin's `examples/` directory.

---

## WordPress filters

### Cart filters

#### `woocommerce_globale_pro_add_cart_product_meta_attributes`

**Constant:** `Model\Cart::FILTER_CART_PRODUCT_META_ATTRIBUTES`  
**File:** `examples/filter_callback_add_cart_product_meta_attributes.php`

Allows adding custom `CustomProductAttribute` objects to a cart product's meta attributes.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Cart::FILTER_CART_PRODUCT_META_ATTRIBUTES,
    'my_callback',
    10,
    2  // $metaAttributes (array), $cart_item (array)
);

function my_callback( array $metaAttributes, array $cart_item ): array {
    $attribute = new \GCBWC\Globale\Pro\Api\Entity\CustomProductAttribute();
    $attribute->setAttributeKey( 'Engraving' );
    $attribute->setAttributeValue( 'John' );
    $metaAttributes[] = $attribute;
    return $metaAttributes;
}
```

---

#### `woocommerce_globale_pro_add_gift_message`

**Constant:** `Model\Cart::FILTER_CART_PRODUCT_GIFT_MESSAGE`  
**File:** `examples/filter_callback_add_gift_message.php`

Allows injecting a gift message string into the cart product payload.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Cart::FILTER_CART_PRODUCT_GIFT_MESSAGE,
    'my_gift_message',
    10,
    2  // $message (string|null), $cart_item (array)
);
```

---

#### `woocommerce_globale_pro_add_extra_virtual_products`

**Constant:** `Model\Cart::FILTER_CART_EXTRA_VIRTUAL_PRODUCTS`  
**File:** `examples/filter_callback_add_extra_virtual_products.php`

Injects extra virtual (non-physical) line items into the cart product list. Useful for warranties, gift wrapping, or other fee products that should appear in the Global-e payload.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Cart::FILTER_CART_EXTRA_VIRTUAL_PRODUCTS,
    'my_extra_products',
    10,
    2  // $products (array of ProductEntity), $cart_item (array)
);
```

---

#### `woocommerce_globale_pro_transform_product_sku`

**Constant:** `Model\Cart::FILTER_CART_TRANSFORM_PRODUCT_SKU`  
**File:** `examples/filter_callback_cart_transform_product_sku.php`

Transforms the SKU that is sent to Global-e for a cart item. Use when your internal SKU format differs from what Global-e expects.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Cart::FILTER_CART_TRANSFORM_PRODUCT_SKU,
    'my_transform_sku',
    10,
    2  // $sku (string), $cart_item (array)
);
```

---

#### `woocommerce_globale_pro_build_product_after`

**Constant:** `Model\Cart::FILTER_CART_BUILD_PRODUCT_AFTER`  
**File:** `examples/filter_callback_build_product_after.php`

Fires after a `ProductEntity` is fully built for a cart item. Use to mutate any field on the entity before it is serialised.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Cart::FILTER_CART_BUILD_PRODUCT_AFTER,
    'my_build_product_after',
    10,
    2  // $product (ProductEntity), $cart_item (array)
);
```

---

#### `woocommerce_globale_pro_modify_discounts`

**Constant:** `Model\Cart::FILTER_CART_MODIFY_DISCOUNTS`  
**File:** `examples/filter_callback_modify_discounts.php`

Allows adding, removing, or modifying discount entries in the cart's `DiscountsList` before the response is sent to Global-e.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Cart::FILTER_CART_MODIFY_DISCOUNTS,
    'my_modify_discounts',
    10,
    2  // $discounts (array of DiscountEntity), $productsList (array)
);
```

---

### Order filters

#### `woocommerce_globale_pro_load_product_by_transformed_sku`

**Constant:** `Model\Order::FILTER_ORDER_LOAD_PRODUCT_BY_TRANSFORMED_SKU`  
**File:** `examples/filter_callback_load_product_by_transformed_sku.php`

Overrides the product lookup during order creation. Return a `\WC_Product` to short-circuit the default SKU/ID lookup. Return `null` to fall through to default behaviour.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Order::FILTER_ORDER_LOAD_PRODUCT_BY_TRANSFORMED_SKU,
    'my_load_product',
    10,
    2  // $product (WC_Product|null), $sku (string)
);
```

---

#### `woocommerce_globale_pro_product_meta_attributes`

**Constant:** `Model\Order::FILTER_ORDER_PRODUCT_META_ATTRIBUTES`  
**File:** `examples/filter_callback_product_metadata_attributes.php`

Modifies the array of custom meta attributes attached to each order line item.

```php
add_filter(
    \GCBWC\Globale\Pro\Model\Order::FILTER_ORDER_PRODUCT_META_ATTRIBUTES,
    'my_order_meta_attrs',
    10,
    2  // $attributes (array), $orderItem (stdClass from request)
);
```

---

#### `woocommerce_globale_pro_extra_virtual_products_to_metadata`

**Constant:** `Model\Order::FILTER_ORDER_EXTRA_VIRTUAL_PRODUCTS_METADATA`  
**File:** `examples/filter_callback_extra_virtual_products_to_metadata.php`

Maps extra virtual product entities (added via `FILTER_CART_EXTRA_VIRTUAL_PRODUCTS`) to order item meta arrays when the order is created.

---

### Price filters

#### `global_pro_cart_get_product_list_price`

**Constant:** `GlobalePro::CART_GET_PRODUCT_LIST_PRICE`

Overrides the list (regular) price for a cart product. Receives `($price, $wcProduct)`.

#### `global_pro_cart_get_product_sale_price`

**Constant:** `GlobalePro::CART_GET_PRODUCT_SALE_PRICE`

Overrides the sale price for a cart product. Receives `($price, $wcProduct)`.

---

### Store code / locale filters

#### `global_pro_get_store_code`

**Constant:** `GlobalePro::STORE_CODE_FILTER`

Return a custom store code string. Used when a single WooCommerce installation serves multiple Global-e merchant configurations.

#### `global_pro_get_store_code_Instance`

**Constant:** `GlobalePro::STORE_CODE_INSTANCE_FILTER`

Return a custom store instance string.

#### `global_pro_get_preferred_culture`

**Constant:** `GlobalePro::PREFERRED_CULTURE_FILTER`

Return a preferred culture/locale string (defaults to `get_locale()`).

---

### Third-party compatibility filters

These are registered automatically; they are documented here for completeness.

| Filter | Purpose |
|---|---|
| `wc_aelia_pbc_customer_country` | Sets country from Global-e cookie for Aelia PBC |
| `wc_aelia_cs_customer_country` | Sets country from Global-e cookie for Aelia CS |
| `wc_aelia_cs_selected_currency` | Sets currency from Global-e cookie for Aelia CS |
| `acfw_get_cart_condition_field_value` | Resolves shipping-zone conditions for Advanced Coupons |
| `wt_alter_sequence_number` | Appends Global-e order number to Sequential Order Numbers |
| `woo_discount_rules_apply_rules` | Ensures WooCommerce Discount Rules run on Global-e API requests |
| `woocommerce_is_rest_api_request` | Returns `true` when `GlobalePro::isRestApi()` is true |

---

## WordPress actions

### `woocommerce_globale_pro_action_clear_cart_after`

**Constant:** `Helper\Session::ACTION_CLEAR_CART_AFTER`  
**File:** `examples/action_callback_clear_cart_after.php`

Fires after the WooCommerce cart has been cleared by `Session::clearCart()`. Use to clear any additional state tied to the shopper's cart (e.g. custom session data, quote entries).

```php
add_action(
    \GCBWC\Globale\Pro\Helper\Session::ACTION_CLEAR_CART_AFTER,
    'my_clear_cart_after'
);
```

---

### `woocommerce_globale_pro_action_handle_product_gift_message`

**Constant:** `Model\Order::ACTION_ORDER_HANDLE_PRODUCT_GIFT_MESSAGE`  
**File:** `examples/action_callback_handle_product_gift_message.php`

Fires during order creation when a gift message is present in the order item. Receives the `WC_Order_Item_Product` and the gift message string; use to store or process the message.

```php
add_action(
    \GCBWC\Globale\Pro\Model\Order::ACTION_ORDER_HANDLE_PRODUCT_GIFT_MESSAGE,
    'my_gift_message_handler',
    10,
    2  // $orderItem (WC_Order_Item_Product), $message (string)
);
```

---

### `woocommerce_globale_pro_action_add_order_item_after`

**Constant:** `Model\Order::ACTION_ORDER_ADD_ORDER_ITEM_AFTER`  
**File:** `examples/action_callback_add_order_item_after.php`

Fires after each line item is added to the WooCommerce order during order creation. Receives the `WC_Order_Item_Product` and the raw product data object from the request. Use to attach custom line-item meta.

```php
add_action(
    \GCBWC\Globale\Pro\Model\Order::ACTION_ORDER_ADD_ORDER_ITEM_AFTER,
    'my_order_item_after',
    10,
    2  // $orderItem (WC_Order_Item_Product), $productData (stdClass)
);
```