Skip to content

Commit 15d0190

Browse files
AugustMillerAugustMiller
committed
Order Condition Formula handling
1 parent e333faf commit 15d0190

2 files changed

Lines changed: 58 additions & 68 deletions

File tree

‎docs/commerce/4.x/discounts.md‎

Lines changed: 29 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -104,60 +104,55 @@ Restrict the discount to a specific time period defined by start and end date fi
104104

105105
### Order Condition Formula
106106

107-
The order condition formula lets you use a simple Twig condition syntax to add a matching rule to the discount.
108-
If the field is left blank, the condition will match the order being matched to the discount (the other conditions will still apply).
107+
The order condition formula lets you define custom logic via a pared-down [Twig expression](https://twig.symfony.com/doc/3.x/templates.html#expressions) that returns `true` or `false`. Formulas are ultimately evaluated as part of an `{% if ... %}` control tag.
109108

110-
The field accepts the [Twig’s expression syntax](https://twig.symfony.com/doc/3.x/templates.html#expressions), which is an expression that returns `true` or `false`.
109+
- If the field is left blank it has no effect on the matching.
110+
- If the expression evaluates to `true` (or any equivalent “[truthy](https://twig.symfony.com/doc/3.x/tags/if.html)” value), the discount _matches_ the order.
111+
- If the expression evaluates to `false` (or any equivalent “falsey” value) the condition _disqualifies_ the order.
111112

112-
If the expression is calculated as `true`, the discount matches the order. If not, the condition disqualifies the order from the discount. An empty condition is the same as a `true` expression.
113-
114-
The condition formula can use an `order` variable, which for safety is an array and not the order element—it’s the same representation of the order you’d see if you exported it from the order index page. This data-only format prevents a store manager from accidentally calling methods like `order.markAsComplete()`.
113+
The condition formula has access to an `order` variable, which (for safety) is an array and not the order element—effectively the same representation of the order you’d see if you exported it from the order index page. This data-only format prevents a store manager from accidentally or maliciously calling methods like `order.markAsComplete()`. The same is true for any nested elements and custom field values—everything is serialized into arrays and scalar values.
115114

116115
::: tip
117-
The condition formula’s `order` array is generated with:
118-
119-
```php
120-
$order->toArray(
121-
[], ['lineItems.snapshot', 'shippingAddress', 'billingAddress']
122-
);
123-
```
116+
As an additional safeguard, only a handful of Twig filters, functions, tags, and variables are available in this context. See <commerce4:craft\commerce\services\Formulas> for a complete list of allowed features.
124117
:::
125118

126119
Here are some examples of an discount’s condition formula:
127120

128-
**Example 1:**
121+
Example 1: Company Email Discount
129122

130-
```twig
131-
'@myclient.com' in order.email
132-
```
123+
: ```twig
124+
'@myclient.com' in order.email
125+
```
133126

134-
The above would be a `true` statement if the order’s email contains the string `@myclient.com`.
127+
The above would be a `true` statement if the order’s email contains the string `@myclient.com`.
135128

136-
This would be a way of giving this discount to anyone from that company.
129+
This would be a way of giving a discount to customers using a specific company’s email address.
137130

138-
**Example 2:**
131+
::: warning
132+
Guest customers do not need to verify the email they use on an order! You may need to use the **Match Customer** condition builder to ensure they are a registered user.
133+
:::
139134

140-
```twig
141-
order.shippingAddressId and order.shippingAddress.zipCode[0:2] == '70'
142-
```
135+
Example 2: Local Customers
143136

144-
The above would be a `true` statement if the order has a shipping address and the shipping address `zipCode` starts with `70`.
137+
: ```twig
138+
order.shippingAddressId and order.shippingAddress.postalCode[0:2] == '70'
139+
```
145140

146-
This would be a way of giving this discount to anyone shipping to that postal code.
141+
The above would be a `true` statement if the order has a shipping address and the shipping address `postalCode` starts with `70`.
147142

148-
**Example 3:**
143+
This would be a way of giving this discount to anyone shipping to that postal code.
149144

150-
```twig
151-
order.myCustomLicenseField and order.myCustomLicenseField == 'Supporter'
152-
```
145+
Example 3: Custom Fields
153146

154-
The above would be a `true` statement if the order has a custom `myCustomLicenseField` field with a value of `Supporter`.
147+
: ```twig
148+
order.myCustomLicenseField and order.myCustomLicenseField == 'Supporter'
149+
```
155150

156-
This would be a way of giving this discount to anyone that’s chosen a specific product license, and you could similarly use it to offer discounts that depend on custom field data.
151+
The above would be a `true` statement if the order has a custom `myCustomLicenseField` field with a value of `Supporter`.
157152

158-
::: tip
159-
For safety, only a serialized representation of order attributes is available; you can’t call custom field methods from a condition formula.
160-
:::
153+
This would be a way of giving this discount to anyone that’s chosen a specific product license, and you could similarly use it to offer discounts that depend on custom field data.
154+
155+
Whenever possible, we recommend implementing **Order Condition Formula** as **Match Order** conditions. Doing so means that we can automatically migrate conditions or provide suggestions during major version upgrades.
161156

162157
### Purchase Total
163158

‎docs/commerce/5.x/system/discounts.md‎

Lines changed: 29 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -72,60 +72,55 @@ Restrict the discount to a specific time period defined by start and end date fi
7272

7373
### Order Condition Formula
7474

75-
The order condition formula lets you use a simple Twig condition syntax to add a matching rule to the discount.
76-
If the field is left blank, the condition will match the order being matched to the discount (the other conditions will still apply).
75+
The order condition formula lets you define custom logic via a pared-down [Twig expression](https://twig.symfony.com/doc/3.x/templates.html#expressions) that returns `true` or `false`. Formulas are ultimately evaluated as part of an `{% if ... %}` control tag.
7776

78-
The field accepts the [Twig’s expression syntax](https://twig.symfony.com/doc/3.x/templates.html#expressions), which is an expression that returns `true` or `false`.
77+
- If the field is left blank it has no effect on the matching.
78+
- If the expression evaluates to `true` (or any equivalent “[truthy](https://twig.symfony.com/doc/3.x/tags/if.html)” value), the discount _matches_ the order.
79+
- If the expression evaluates to `false` (or any equivalent “falsey” value) the condition _disqualifies_ the order.
7980

80-
If the expression is calculated as `true`, the discount matches the order. If not, the condition disqualifies the order from the discount. An empty condition is the same as a `true` expression.
81-
82-
The condition formula can use an `order` variable, which for safety is an array and not the order element—it’s the same representation of the order you’d see if you exported it from the order index page. This data-only format prevents a store manager from accidentally calling methods like `order.markAsComplete()`.
81+
The condition formula has access to an `order` variable, which (for safety) is an array and not the order element—effectively the same representation of the order you’d see if you exported it from the order index page. This data-only format prevents a store manager from accidentally or maliciously calling methods like `order.markAsComplete()`. The same is true for any nested elements and custom field values—everything is serialized into arrays and scalar values.
8382

8483
::: tip
85-
The condition formula’s `order` array is generated with:
86-
87-
```php
88-
$order->toArray(
89-
[], ['lineItems.snapshot', 'shippingAddress', 'billingAddress']
90-
);
91-
```
84+
As an additional safeguard, only a handful of Twig filters, functions, tags, and variables are available in this context. See <commerce5:craft\commerce\services\Formulas> for a complete list of allowed features.
9285
:::
9386

9487
Here are some examples of an discount’s condition formula:
9588

96-
**Example 1:**
89+
Example 1: Company Email Discount
9790

98-
```twig
99-
'@myclient.com' in order.email
100-
```
91+
: ```twig
92+
'@myclient.com' in order.email
93+
```
10194

102-
The above would be a `true` statement if the order’s email contains the string `@myclient.com`.
95+
The above would be a `true` statement if the order’s email contains the string `@myclient.com`.
10396

104-
This would be a way of giving this discount to anyone from that company.
97+
This would be a way of giving a discount to customers using a specific company’s email address.
10598

106-
**Example 2:**
99+
::: warning
100+
Guest customers do not need to verify the email they use on an order! You may need to use the **Match Customer** condition builder to ensure they are a registered user.
101+
:::
107102

108-
```twig
109-
order.shippingAddressId and order.shippingAddress.zipCode[0:2] == '70'
110-
```
103+
Example 2: Local Customers
111104

112-
The above would be a `true` statement if the order has a shipping address and the shipping address `zipCode` starts with `70`.
105+
: ```twig
106+
order.shippingAddressId and order.shippingAddress.postalCode[0:2] == '70'
107+
```
113108

114-
This would be a way of giving this discount to anyone shipping to that postal code.
109+
The above would be a `true` statement if the order has a shipping address and the shipping address `postalCode` starts with `70`.
115110

116-
**Example 3:**
111+
This would be a way of giving this discount to anyone shipping to that postal code.
117112

118-
```twig
119-
order.myCustomLicenseField and order.myCustomLicenseField == 'Supporter'
120-
```
113+
Example 3: Custom Fields
121114

122-
The above would be a `true` statement if the order has a custom `myCustomLicenseField` field with a value of `Supporter`.
115+
: ```twig
116+
order.myCustomLicenseField and order.myCustomLicenseField == 'Supporter'
117+
```
123118

124-
This would be a way of giving this discount to anyone that’s chosen a specific product license, and you could similarly use it to offer discounts that depend on custom field data.
119+
The above would be a `true` statement if the order has a custom `myCustomLicenseField` field with a value of `Supporter`.
125120

126-
::: tip
127-
For safety, only a serialized representation of order attributes is available; you can’t call custom field methods from a condition formula.
128-
:::
121+
This would be a way of giving this discount to anyone that’s chosen a specific product license, and you could similarly use it to offer discounts that depend on custom field data.
122+
123+
Whenever possible, we recommend implementing **Order Condition Formula** as **Match Order** conditions. Doing so means that we can automatically migrate conditions or provide suggestions during major version upgrades.
129124

130125
### Purchase Total
131126

0 commit comments

Comments
 (0)