Settings
- Type
- Class
- Namespace
- craft\commerce\models
- Inherits
- craft\commerce\models\Settings » craft\commerce\base\Model » craft\base\Model (opens new window) » yii\base\Model (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
- Implements
- ArrayAccess (opens new window), IteratorAggregate (opens new window), craft\base\ModelInterface (opens new window), yii\base\Arrayable (opens new window), yii\base\Configurable (opens new window), yii\base\StaticInstanceInterface (opens new window)
- Uses traits
- craft\base\ClonefixTrait (opens new window), yii\base\ArrayableTrait (opens new window), yii\base\StaticInstanceTrait (opens new window)
- Since
- 2.0
Settings model.
View source (opens new window)
# Public Properties
| Property | Description |
|---|---|
| activeCartDuration | mixed – How long a cart should go without being updated before it’s considered inactive. |
| activeValidators (opens new window) | yii\validators\Validator (opens new window) – The validators applicable to the current scenario (opens new window). |
| allowCheckoutWithoutPayment | boolean (opens new window) – Whether carts are can be marked as completed without a payment. |
| allowEmptyCartOnCheckout | boolean (opens new window) – Whether carts are allowed to be empty on checkout. |
| allowPartialPaymentOnCheckout | boolean (opens new window) – Whether [partial payment](making-payments. |
| attributes (opens new window) | array (opens new window) – Attribute values (name => value). |
| autoSetCartShippingMethodOption | boolean (opens new window) – Whether the first available shipping method option should be set automatically on carts. |
| autoSetNewCartAddresses | boolean (opens new window) – Whether the user’s primary shipping and billing addresses should be set automatically on new carts. |
| autoSetPaymentSource | boolean (opens new window) – Whether the user’s primary payment source should be set automatically on new carts. |
| behaviors (opens new window) | yii\base\Behavior (opens new window) – List of behaviors attached to this component. |
| cartVariable | string (opens new window) – Key to be used when returning cart information in a response. |
| defaultView | string (opens new window) – Commerce’s default control panel view. |
| defaultViewOptions | array (opens new window) |
| dimensionUnits | string (opens new window) – Unit type for dimension measurements. |
| dimensionsUnits | array (opens new window) |
| emailSenderAddress | string (opens new window), null (opens new window) – Default email address Commerce system messages should be sent from. |
| emailSenderAddressPlaceholder | string (opens new window), null (opens new window) – Placeholder value displayed for the sender address control panel settings field. |
| emailSenderName | string (opens new window), null (opens new window) – Default from name used for Commerce system emails. |
| emailSenderNamePlaceholder | string (opens new window), null (opens new window) – Placeholder value displayed for the sender name control panel settings field. |
| errors (opens new window) | array (opens new window) – Errors for all attributes or the specified attribute. |
| firstErrors (opens new window) | array (opens new window) – The first errors. |
| freeOrderPaymentStrategy | string (opens new window) – How Commerce should handle free orders. |
| freeOrderPaymentStrategyOptions | array (opens new window) |
| gatewayPostRedirectTemplate | string (opens new window) – The path to the template that should be used to perform POST requests to offsite payment gateways. |
| iterator (opens new window) | ArrayIterator (opens new window) – An iterator for traversing the items in the list. |
| loadCartRedirectUrl | string (opens new window), null (opens new window) – Default URL to be loaded after using the [load cart controller action](orders-carts. |
| minimumTotalPriceStrategy | string (opens new window) – How Commerce should handle minimum total price for an order. |
| minimumTotalPriceStrategyOptions | array (opens new window) |
| orderReferenceFormat | string (opens new window) – Human-friendly reference number format for orders. |
| paymentCurrency | array (opens new window), null (opens new window) – ISO codes for supported payment currencies. |
| pdfAllowRemoteImages | boolean (opens new window) – Whether to allow non-local images in generated order PDFs. |
| pdfPaperOrientation | string (opens new window) – The orientation of the paper to use for generated order PDF files. |
| pdfPaperSize | string (opens new window) – The size of the paper to use for generated order PDFs. |
| purgeInactiveCarts | boolean (opens new window) – Whether inactive carts should automatically be deleted from the database during garbage collection. |
| purgeInactiveCartsDuration | mixed – Default length of time before inactive carts are purged. |
| requireBillingAddressAtCheckout | boolean (opens new window) – Whether a billing address is required before making payment on an order. |
| requireShippingAddressAtCheckout | boolean (opens new window) – Whether a shipping address is required before making payment on an order. |
| requireShippingMethodSelectionAtCheckout | boolean (opens new window) – Whether shipping method selection is required before making payment on an order. |
| scenario (opens new window) | string (opens new window) – The scenario that this model is in. |
| showEditUserCommerceTab | boolean (opens new window) – Whether the [Commerce Tab](customers. |
| updateBillingDetailsUrl | string (opens new window) – URL for a user to resolve billing issues with their subscription. |
| updateCartSearchIndexes | boolean (opens new window) – Whether the search index for a cart should be updated when saving the cart via commerce/cart/* controller actions. |
| useBillingAddressForTax | boolean (opens new window) – Whether taxes should be calculated based on the billing address instead of the shipping address. |
| validateBusinessTaxIdAsVatId | boolean (opens new window) – Whether to enable validation requiring the businessTaxId to be a valid VAT ID. |
| validateCartCustomFieldsOnSubmission | boolean (opens new window) – Whether to validate custom fields when a cart is updated. |
| validators (opens new window) | ArrayObject (opens new window), yii\validators\Validator (opens new window) – All the validators declared in the model. |
| weightUnits | string (opens new window) – Units to be used for weight measurements. |
| weightUnitsOptions | array (opens new window) |
# activeCartDuration
- Type
mixed- Default value
3600(1 hour)- Since
- 2.2
How long a cart should go without being updated before it’s considered inactive.
See craft\helpers\ConfigHelper::durationInSeconds() for a list of supported value types.
View source (opens new window)
# allowCheckoutWithoutPayment
- Type
- boolean (opens new window)
- Default value
false- Since
- 3.3
Whether carts are can be marked as completed without a payment.
View source (opens new window)
# allowEmptyCartOnCheckout
- Type
- boolean (opens new window)
- Default value
false- Since
- 2.2
Whether carts are allowed to be empty on checkout.
View source (opens new window)
# allowPartialPaymentOnCheckout
- Type
- boolean (opens new window)
- Default value
false
Whether partial payment can be made from the front end when the gateway allows them.
The false default does not allow partial payments on the front end.
View source (opens new window)
# autoSetCartShippingMethodOption
- Type
- boolean (opens new window)
- Default value
false
Whether the first available shipping method option should be set automatically on carts.
View source (opens new window)
# autoSetNewCartAddresses
- Type
- boolean (opens new window)
- Default value
true
Whether the user’s primary shipping and billing addresses should be set automatically on new carts.
View source (opens new window)
# autoSetPaymentSource
- Type
- boolean (opens new window)
- Default value
false- Since
- 4.2
Whether the user’s primary payment source should be set automatically on new carts.
View source (opens new window)
# cartVariable
- Type
- string (opens new window)
- Default value
'cart'
Key to be used when returning cart information in a response.
View source (opens new window)
# defaultView
- Type
- string (opens new window)
- Default value
'commerce/orders'- Since
- 2.2
Commerce’s default control panel view. (Defaults to order index.)
View source (opens new window)
# defaultViewOptions
- Type
- array (opens new window)
- Default value
null
View source (opens new window)
# dimensionUnits
- Type
- string (opens new window)
- Default value
'mm'
Unit type for dimension measurements.
Options:
'mm''cm''m''ft''in'
View source (opens new window)
# dimensionsUnits
- Type
- array (opens new window)
- Default value
null
View source (opens new window)
# emailSenderAddress
- Type
- string (opens new window), null (opens new window)
- Default value
null
Default email address Commerce system messages should be sent from.
If null (default), Craft’s MailSettings::$fromEmail will be used.
View source (opens new window)
# emailSenderAddressPlaceholder
- Type
- string (opens new window), null (opens new window)
- Default value
null
Placeholder value displayed for the sender address control panel settings field.
If null (default), Craft’s MailSettings::$fromEmail will be used.
View source (opens new window)
# emailSenderName
- Type
- string (opens new window), null (opens new window)
- Default value
null
Default from name used for Commerce system emails.
If null (default), Craft’s MailSettings::$fromName will be used.
View source (opens new window)
# emailSenderNamePlaceholder
- Type
- string (opens new window), null (opens new window)
- Default value
null
Placeholder value displayed for the sender name control panel settings field.
If null (default), Craft’s MailSettings::$fromName will be used.
View source (opens new window)
# freeOrderPaymentStrategy
- Type
- string (opens new window)
- Default value
'complete'
How Commerce should handle free orders.
The default 'complete' setting automatically completes zero-balance orders without forwarding them to the payment gateway.
The 'process' setting forwards zero-balance orders to the payment gateway for processing. This can be useful if the customer’s balance
needs to be updated or otherwise adjusted by the payment gateway.
View source (opens new window)
# freeOrderPaymentStrategyOptions
- Type
- array (opens new window)
- Default value
null
View source (opens new window)
# gatewayPostRedirectTemplate
- Type
- string (opens new window)
- Default value
''
The path to the template that should be used to perform POST requests to offsite payment gateways.
The template must contain a form that posts to the URL supplied by the actionUrl variable and outputs all hidden inputs with
the inputs variable.
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Redirecting...</title>
</head>
<body onload="document.forms[0].submit();">
<form action="{{ actionUrl }}" method="post">
<p>Redirecting to payment page...</p>
<p>
{{ inputs|raw }}
<button type="submit">Continue</button>
</p>
</form>
</body>
</html>
TIP
Since this template is simply used for redirecting, it only appears for a few seconds, so we suggest making it load fast with minimal images and inline styles to reduce HTTP requests.
If empty (default), each gateway will decide how to handle after-payment redirects.
View source (opens new window)
# loadCartRedirectUrl
- Type
- string (opens new window), null (opens new window)
- Default value
null- Since
- 3.1
Default URL to be loaded after using the load cart controller action.
If null (default), Craft’s default siteUrl will be used.
View source (opens new window)
# minimumTotalPriceStrategy
- Type
- string (opens new window)
- Default value
'default'
How Commerce should handle minimum total price for an order.
Options:
'default'rounds the sum of the item subtotal and adjustments.'zero'returns0if the result from'default'would’ve been negative; minimum order total is0.'shipping'returns the total shipping cost if the'default'result would’ve been negative; minimum order total equals shipping amount.
View source (opens new window)
# minimumTotalPriceStrategyOptions
- Type
- array (opens new window)
- Default value
null
View source (opens new window)
# orderReferenceFormat
- Type
- string (opens new window)
- Default value
'{{number[:7]}}'
Human-friendly reference number format for orders. Result must be unique.
See Order Numbers.
View source (opens new window)
# paymentCurrency
- Type
- array (opens new window), null (opens new window)
- Default value
null
ISO codes for supported payment currencies.
See Payment Currencies.
View source (opens new window)
# pdfAllowRemoteImages
- Type
- boolean (opens new window)
- Default value
false
Whether to allow non-local images in generated order PDFs.
View source (opens new window)
# pdfPaperOrientation
- Type
- string (opens new window)
- Default value
'portrait'
The orientation of the paper to use for generated order PDF files.
Options are 'portrait' and 'landscape'.
View source (opens new window)
# pdfPaperSize
- Type
- string (opens new window)
- Default value
'letter'
The size of the paper to use for generated order PDFs.
The full list of supported paper sizes can be found in the dompdf library (opens new window).
View source (opens new window)
# purgeInactiveCarts
- Type
- boolean (opens new window)
- Default value
true
Whether inactive carts should automatically be deleted from the database during garbage collection.
TIP
You can control how long a cart should go without being updated before it gets deleted purgeInactiveCartsDuration setting.
View source (opens new window)
# purgeInactiveCartsDuration
- Type
mixed- Default value
7776000(90 days)
Default length of time before inactive carts are purged. (Defaults to 90 days.)
See craft\helpers\ConfigHelper::durationInSeconds() for a list of supported value types.
View source (opens new window)
# requireBillingAddressAtCheckout
- Type
- boolean (opens new window)
- Default value
false
Whether a billing address is required before making payment on an order.
View source (opens new window)
# requireShippingAddressAtCheckout
- Type
- boolean (opens new window)
- Default value
false
Whether a shipping address is required before making payment on an order.
View source (opens new window)
# requireShippingMethodSelectionAtCheckout
- Type
- boolean (opens new window)
- Default value
false
Whether shipping method selection is required before making payment on an order.
View source (opens new window)
# showEditUserCommerceTab
- Type
- boolean (opens new window)
- Default value
true- Since
- 4.0
Whether the Commerce Tab should be shown when viewing users in the control panel.
View source (opens new window)
# updateBillingDetailsUrl
- Type
- string (opens new window)
- Default value
''
URL for a user to resolve billing issues with their subscription.
TIP
The example templates include a template for this page (opens new window).
View source (opens new window)
# updateCartSearchIndexes
- Type
- boolean (opens new window)
- Default value
true- Since
- 3.1.5
Whether the search index for a cart should be updated when saving the cart via commerce/cart/* controller actions.
May be set to false to reduce performance impact on high-traffic sites.
WARNING
Setting this to false will result in fewer index update queue jobs, but you’ll need to manually re-index orders to ensure up-to-date cart search results in the control panel.
View source (opens new window)
# useBillingAddressForTax
- Type
- boolean (opens new window)
- Default value
false
Whether taxes should be calculated based on the billing address instead of the shipping address.
View source (opens new window)
# validateBusinessTaxIdAsVatId
- Type
- boolean (opens new window)
- Default value
false
Whether to enable validation requiring the businessTaxId to be a valid VAT ID.
When set to false, no validation is applied to businessTaxId.
When set to true, businessTaxId must contain a valid VAT ID.
TIP
This setting strictly toggles input validation and has no impact on tax configuration or behavior elsewhere in the system.
View source (opens new window)
# validateCartCustomFieldsOnSubmission
- Type
- boolean (opens new window)
- Default value
false- Since
- 3.0.12
Whether to validate custom fields when a cart is updated.
Set to true to allow custom content fields to return validation errors when a cart is updated.
View source (opens new window)
# weightUnits
- Type
- string (opens new window)
- Default value
'g'
Units to be used for weight measurements.
Options:
'g''kg''lb'
View source (opens new window)
# weightUnitsOptions
- Type
- array (opens new window)
- Default value
null
View source (opens new window)
# Public Methods
| Method | Description |
|---|---|
| __call() (opens new window) | Calls the named method which is not a class method. |
| __clone() (opens new window) | |
| __construct() (opens new window) | |
| __get() (opens new window) | Returns the value of a component property. |
| __isset() (opens new window) | Checks if a property is set, i.e. defined and not null. |
| __set() (opens new window) | Sets the value of a component property. |
| __unset() (opens new window) | Sets a component property to be null. |
| activeAttributes() (opens new window) | Returns the attribute names that are subject to validation in the current scenario. |
| addError() (opens new window) | Adds a new error to the specified attribute. |
| addErrors() (opens new window) | Adds a list of errors. |
| addModelErrors() (opens new window) | Adds errors from another model, with a given attribute name prefix. |
| afterValidate() (opens new window) | This method is invoked after validation ends. |
| attachBehavior() (opens new window) | Attaches a behavior to this component. |
| attachBehaviors() (opens new window) | Attaches a list of behaviors to the component. |
| attributeHints() (opens new window) | Returns the attribute hints. |
| attributeLabels() (opens new window) | Returns the attribute labels. |
| attributes() (opens new window) | Returns the list of attribute names. |
| beforeValidate() (opens new window) | This method is invoked before validation starts. |
| behaviors() (opens new window) | Returns a list of behaviors that this component should behave as. |
| canGetProperty() (opens new window) | Returns a value indicating whether a property can be read. |
| canSetProperty() (opens new window) | Returns a value indicating whether a property can be set. |
| className() (opens new window) | Returns the fully qualified name of this class. |
| clearErrors() (opens new window) | Removes errors for all attributes or a single attribute. |
| createValidators() (opens new window) | Creates validator objects based on the validation rules specified in rules() (opens new window). |
| datetimeAttributes() (opens new window) | Returns the names of any attributes that should hold DateTime (opens new window) values. |
| detachBehavior() (opens new window) | Detaches a behavior from the component. |
| detachBehaviors() (opens new window) | Detaches all behaviors from the component. |
| ensureBehaviors() (opens new window) | Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component. |
| extraFields() (opens new window) | Returns the list of fields that can be expanded further and returned by toArray() (opens new window). |
| fields() (opens new window) | Returns the list of fields that should be returned by default by toArray() (opens new window) when no specific fields are specified. |
| formName() (opens new window) | Returns the form name that this model class should use. |
| generateAttributeLabel() (opens new window) | Generates a user friendly attribute label based on the give attribute name. |
| getActiveValidators() (opens new window) | Returns the validators applicable to the current scenario (opens new window). |
| getAttributeHint() (opens new window) | Returns the text hint for the specified attribute. |
| getAttributeLabel() (opens new window) | Returns the text label for the specified attribute. |
| getAttributes() (opens new window) | Returns attribute values. |
| getBehavior() (opens new window) | Returns the named behavior object. |
| getBehaviors() (opens new window) | Returns all behaviors attached to this component. |
| getDefaultViewOptions() | Returns a key-value array of default control panel view options and labels. |
| getDimensionUnits() | Returns a key-value array of dimension unit options and labels. |
| getErrorSummary() (opens new window) | Returns the errors for all attributes as a one-dimensional array. |
| getErrors() (opens new window) | Returns the errors for all attributes or a single attribute. |
| getFirstError() (opens new window) | Returns the first error of the specified attribute. |
| getFirstErrors() (opens new window) | Returns the first error of every attribute in the model. |
| getFreeOrderPaymentStrategyOptions() | Returns a key-value array of freeOrderPaymentStrategy options and labels. |
| getIterator() (opens new window) | Returns an iterator for traversing the attributes in the model. |
| getMinimumTotalPriceStrategyOptions() | Returns a key-value array of minimumTotalPriceStrategy options and labels. |
| getPaymentCurrency() | Returns the ISO payment currency for a given site, or the default site if no handle is provided. |
| getScenario() (opens new window) | Returns the scenario that this model is used in. |
| getValidators() (opens new window) | Returns all the validators declared in rules() (opens new window). |
| getWeightUnitsOptions() | Returns a key-value array of weight unit options and labels. |
| hasErrors() (opens new window) | Returns a value indicating whether there is any validation error. |
| hasEventHandlers() (opens new window) | Returns a value indicating whether there is any handler attached to the named event. |
| hasMethod() (opens new window) | Returns a value indicating whether a method is defined. |
| hasProperty() (opens new window) | Returns a value indicating whether a property is defined for this component. |
| init() (opens new window) | Initializes the object. |
| instance() (opens new window) | Returns static class instance, which can be used to obtain meta information. |
| isAttributeActive() (opens new window) | Returns a value indicating whether the attribute is active in the current scenario. |
| isAttributeRequired() (opens new window) | Returns a value indicating whether the attribute is required. |
| isAttributeSafe() (opens new window) | Returns a value indicating whether the attribute is safe for massive assignments. |
| load() (opens new window) | Populates the model with input data. |
| loadMultiple() (opens new window) | Populates a set of models with the data from end user. |
| off() (opens new window) | Detaches an existing event handler from this component. |
| offsetExists() (opens new window) | Returns whether there is an element at the specified offset. |
| offsetGet() (opens new window) | Returns the element at the specified offset. |
| offsetSet() (opens new window) | Sets the element at the specified offset. |
| offsetUnset() (opens new window) | Sets the element value at the specified offset to null. |
| on() (opens new window) | Attaches an event handler to an event. |
| onUnsafeAttribute() (opens new window) | This method is invoked when an unsafe attribute is being massively assigned. |
| rules() (opens new window) | Returns the validation rules for attributes. |
| safeAttributes() (opens new window) | Returns the attribute names that are safe to be massively assigned in the current scenario. |
| scenarios() (opens new window) | Returns a list of scenarios and the corresponding active attributes. |
| setAttributes() | Sets the attribute values in a massive way. |
| setScenario() (opens new window) | Sets the scenario for the model. |
| toArray() (opens new window) | Converts the model into an array. |
| trigger() (opens new window) | Triggers an event. |
| validate() (opens new window) | Performs the data validation. |
| validateMultiple() (opens new window) | Validates multiple models. |
# getDefaultViewOptions()
- Since
- 2.2
Returns a key-value array of default control panel view options and labels.
View source (opens new window)
# getDimensionUnits()
Returns a key-value array of dimension unit options and labels.
View source (opens new window)
# getFreeOrderPaymentStrategyOptions()
Returns a key-value array of freeOrderPaymentStrategy options and labels.
View source (opens new window)
# getMinimumTotalPriceStrategyOptions()
Returns a key-value array of minimumTotalPriceStrategy options and labels.
View source (opens new window)
# getPaymentCurrency()
Returns the ISO payment currency for a given site, or the default site if no handle is provided.
View source (opens new window)
Arguments
$siteHandle(string (opens new window), null (opens new window))
Throws
- yii\base\InvalidConfigException (opens new window)
if the currency in the config file is not set up - craft\commerce\errors\CurrencyException
# getWeightUnitsOptions()
Returns a key-value array of weight unit options and labels.
View source (opens new window)
# setAttributes()
Sets the attribute values in a massive way.
View source (opens new window)
Arguments
$values(array (opens new window)) – Attribute values (name => value) to be assigned to the model.$safeOnly(boolean (opens new window)) – Whether the assignments should only be done to the safe attributes. A safe attribute is one that is associated with a validation rule in the current scenario (opens new window).
# Protected Methods
| Method | Description |
|---|---|
| defineBehaviors() (opens new window) | Returns the behaviors to attach to this class. |
| defineRules() | Returns the validation rules for attributes. |
| extractFieldsFor() (opens new window) | Extract nested fields from a fields collection for a given root field Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "id". |
| extractRootFields() (opens new window) | Extracts the root field names from nested fields. |
| resolveFields() (opens new window) | Determines which fields can be returned by toArray() (opens new window). |
# defineRules()
Returns the validation rules for attributes.
See rules() (opens new window) for details about what should be returned.
Models should override this method instead of rules() (opens new window) so EVENT_DEFINE_RULES (opens new window) handlers can modify the class-defined rules.
View source (opens new window)
Returns
# Constants
| Constant | Description |
|---|---|
FREE_ORDER_PAYMENT_STRATEGY_COMPLETE | |
FREE_ORDER_PAYMENT_STRATEGY_PROCESS | |
MINIMUM_TOTAL_PRICE_STRATEGY_DEFAULT | |
MINIMUM_TOTAL_PRICE_STRATEGY_SHIPPING | |
MINIMUM_TOTAL_PRICE_STRATEGY_ZERO | |
SCENARIO_DEFAULT | The name of the default scenario. |
VIEW_URI_CUSTOMERS | |
VIEW_URI_ORDERS | |
VIEW_URI_PRODUCTS | |
VIEW_URI_PROMOTIONS | |
VIEW_URI_SHIPPING | |
VIEW_URI_SUBSCRIPTIONS | |
VIEW_URI_TAX |