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), 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).
allowEmptyCartOnCheckout boolean (opens new window) – Whether carts are allowed to be empty on checkout.
attributes (opens new window) array (opens new window) – Attribute values (name => value).
autoSetNewCartAddresses boolean (opens new window) – Whether the customer’s primary shipping and billing addresses 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.
emailSenderAddress string (opens new window) – Default email address Commerce system messages should be sent from.
emailSenderAddressPlaceholder string (opens new window) – Placeholder value displayed for the sender address control panel settings field.
emailSenderName string (opens new window) – Default from name used for Commerce system emails.
emailSenderNamePlaceholder string (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.
gatewaySettings array (opens new window) – Payment gateway settings indexed by each gateway’s handle.
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](loading-a-cart.
minimumTotalPriceStrategy string (opens new window) – How Commerce should handle minimum total price for an order.
minimumTotalPriceStrategyOptions array (opens new window)
orderPdfFilenameFormat string (opens new window) – Filename format to be used for order PDFs.
orderPdfPath string (opens new window) – Path to the template to be used for order PDFs.
orderReferenceFormat string (opens new window) – Human-friendly reference number format for orders.
paymentCurrency array (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.
showCustomerInfoTab boolean (opens new window) – Whether the [customer info 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. (Defaults to one day.)

See craft\helpers\ConfigHelper::durationInSeconds() for a list of supported value types.

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)

# autoSetNewCartAddresses

Type
boolean (opens new window)
Default value
true

Whether the customer’s primary shipping and billing addresses 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
Access
Read-only
Since
2.2

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)

# emailSenderAddress

Type
string (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)
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)
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)
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
Access
Read-only

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 }}
        <input type="submit" value="Continue">
    </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)

# gatewaySettings

Type
array (opens new window)
Default value
[]

Payment gateway settings indexed by each gateway’s handle.

Check each gateway’s documentation for settings that may be stored.

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' returns 0 if the result from 'default' would’ve been negative; minimum order total is 0.
  • '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
Access
Read-only

View source (opens new window)

# orderPdfFilenameFormat

DEPRECATED

Deprecated in 3.2.0. Use Default PDF instead.

Type
string (opens new window)
Default value
'Order-{number}'

Filename format to be used for order PDFs.

View source (opens new window)

# orderPdfPath

DEPRECATED

Deprecated in 3.2.0. Use Default PDF instead.

Type
string (opens new window)
Default value
'shop/special/receipt'

Path to the template to be used for order PDFs.

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)
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)

# showCustomerInfoTab

Type
boolean (opens new window)
Default value
true
Since
3.0

Whether the customer info 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
Access
Read-only

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) Constructor.
__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.
defineRules() Returns the validation rules for attributes.
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.
getError() (opens new window) Returns the first error of the specified attribute.
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() (opens new window) 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.

# 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

array (opens new window)

# getDefaultViewOptions()

Since
2.2

Returns a key-value array of default control panel view options and labels.

View source (opens new window)

Returns

array (opens new window)

# getDimensionUnits()

Returns a key-value array of dimension unit options and labels.

View source (opens new window)

Returns

array (opens new window)

# getFreeOrderPaymentStrategyOptions()

Returns a key-value array of freeOrderPaymentStrategy options and labels.

View source (opens new window)

Returns

array (opens new window)

# getMinimumTotalPriceStrategyOptions()

Returns a key-value array of minimumTotalPriceStrategy options and labels.

View source (opens new window)

Returns

array (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

Returns

string (opens new window), null (opens new window)

Throws

# getWeightUnitsOptions()

Returns a key-value array of weight unit options and labels.

View source (opens new window)

Returns

array (opens new window)

# Protected Methods

Method Description
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).

# 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