GeneralConfig

Type
Class
Namespace
craft\config
Inherits
craft\config\GeneralConfig » yii\base\BaseObject
Implements
yii\base\Configurable
Since
3.0.0

General config class

View source

# Public Properties

Property Description
actionTrigger string – The URI segment Craft should look for when determining if the current request should be routed to a controller action.
activateAccountSuccessPath mixed – The URI that users without access to the control panel should be redirected to after activating their account.
addTrailingSlashesToUrls boolean – Whether auto-generated URLs should have trailing slashes.
aliases array – Any custom Yii [aliases](https://www.
allowAdminChanges boolean – Whether admins should be allowed to make administrative changes to the system.
allowSimilarTags boolean – Whether users should be allowed to create similarly-named tags.
allowUpdates boolean – Whether Craft should allow system and plugin updates in the control panel, and plugin installation from the Plugin Store.
allowUppercaseInSlug boolean – Whether uppercase letters should be allowed in slugs.
allowedFileExtensions string[] – The file extensions Craft should allow when a user is uploading files.
autoLoginAfterAccountActivation boolean – Whether users should automatically be logged in after activating their account or resetting their password.
backupCommand string, null – The shell command that Craft should execute to create a database backup.
backupOnUpdate boolean – Whether Craft should create a database backup before applying a new system update.
baseCpUrl string, null – The base URL that Craft should use when generating control panel URLs.
blowfishHashCost integer – The higher the cost value, the longer it takes to generate a password hash and to verify against it.
cacheDuration mixed – The default length of time Craft will store data, RSS feed, and template caches.
cacheElementQueries boolean – Whether Craft should cache element queries that fall inside {% cache %} tags.
convertFilenamesToAscii boolean – Whether uploaded filenames with non-ASCII characters should be converted to ASCII (i.e. ñn).
cooldownDuration mixed – The amount of time a user must wait before re-attempting to log in after their account is locked due to too many failed login attempts.
cpTrigger string – The URI segment Craft should look for when determining if the current request should route to the control panel rather than the front-end website.
csrfTokenName string – The name of CSRF token used for CSRF validation if enableCsrfProtection is set to true.
customAsciiCharMappings array – Any custom ASCII character mappings.
defaultCookieDomain string – The domain that cookies generated by Craft should be created for.
defaultCpLanguage string, null – The default language the control panel should use for users who haven’t set a preferred language yet.
defaultDirMode mixed – The default permission to be set for newly generated directories.
defaultFileMode integer, null – The default permission to be set for newly generated files.
defaultImageQuality integer – The quality level Craft will use when saving JPG and PNG files.
defaultSearchTermOptions array – The default options that should be applied to each search term.
defaultTemplateExtensions string[] – The template file extensions Craft will look for when matching a template path to a file on the front end.
defaultTokenDuration mixed – The default amount of time tokens can be used before expiring.
defaultWeekStartDay integer – The default day that new users should have set as their Week Start Day.
deferPublicRegistrationPassword boolean – By default, Craft will require a 'password' field to be submitted on front-end, public user registrations.
devMode boolean – Whether the system should run in [Dev Mode](https://craftcms.
disabledPlugins string[] – Array of plugin handles that should be disabled, regardless of what the project config says.
elevatedSessionDuration mixed – The amount of time a user’s elevated session will last, which is required for some sensitive actions (e.g. user group/permission assignment).
enableCsrfCookie boolean – Whether to use a cookie to persist the CSRF token if enableCsrfProtection is enabled.
enableCsrfProtection boolean – Whether to enable CSRF protection via hidden form inputs for all forms submitted via Craft.
enableGql boolean – Whether the GraphQL API should be enabled.
enableGraphQlCaching boolean – Whether Craft should cache GraphQL queries.
enableTemplateCaching boolean – Whether to enable Craft's template {% cache %} tag on a global basis.
errorTemplatePrefix string – The prefix that should be prepended to HTTP error status codes when determining the path to look for an error’s template.
extraAllowedFileExtensions string[], null – List of file extensions that will be merged into the allowedFileExtensions config setting.
extraAppLocales string[], null – List of extra locale IDs that the application should support, and users should be able to select as their Preferred Language.
extraFileKinds array – List of additional file kinds Craft should support.
filenameWordSeparator string, boolean – The string to use to separate words when uploading Assets.
generateTransformsBeforePageLoad boolean – Whether images transforms should be generated before page load.
headlessMode boolean – Bool Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations.
imageDriver mixed – The image driver Craft should use to cleanse and transform images.
indexTemplateFilenames string[] – The template filenames Craft will look for within a directory to represent the directory’s “index” template when matching a template path to a file on the front end.
invalidLoginWindowDuration mixed – The amount of time to track invalid login attempts for a user, for determining if Craft should lock an account.
invalidUserTokenPath mixed – The URI Craft should redirect to when user token validation fails.
ipHeaders string[], null – List of headers where proxies store the real client IP.
isSystemLive boolean, null – Whether the site is currently live.
limitAutoSlugsToAscii boolean – Whether non-ASCII characters in auto-generated slugs should be converted to ASCII (i.e. ñ → n).
loginPath mixed – The URI Craft should use for user login on the front-end.
logoutPath mixed – The URI Craft should use for user logout on the front-end.
maxBackups integer, false – The number of backups that Craft should make before it starts deleting the oldest backups.
maxCachedCloudImageSize integer – The maximum dimension size to use when caching images from external sources to use in transforms.
maxInvalidLogins integer – The number of invalid login attempts Craft will allow within the specified duration before the account gets locked.
maxRevisions integer, null – The maximum number of revisions that should be stored for each element.
maxSlugIncrement integer – The highest number Craft will tack onto a slug in order to make it unique before giving up and throwing an error.
maxUploadFileSize integer, string – The maximum upload file size allowed.
omitScriptNameInUrls boolean – Whether generated URLs should omit `index.
optimizeImageFilesize boolean – Whether Craft should optimize images for reduced file sizes without noticeably reducing image quality.
pageTrigger string – The string preceding a number which Craft will look for when determining if the current request is for a particular page in a paginated list of pages.
pathParam string – The query string param that Craft will check when determining the request's path.
phpMaxMemoryLimit string, null – The maximum amount of memory Craft will try to reserve during memory intensive operations such as zipping, unzipping and updating.
phpSessionName string – The name of the PHP session cookie.
postCpLoginRedirect mixed – The path that users should be redirected to after logging in from the control panel.
postLoginRedirect mixed – The path that users should be redirected to after logging in from the front-end site.
postLogoutRedirect mixed – The path that users should be redirected to after logging out from the front-end site.
preserveCmykColorspace boolean – Whether CMYK should be preserved as the colorspace when manipulating images.
preserveExifData boolean – Whether the EXIF data should be preserved when manipulating and uploading images.
preserveImageColorProfiles boolean – Whether the embedded Image Color Profile (ICC) should be preserved when manipulating images.
preventUserEnumeration boolean – When set to false and you go through the "forgot password" workflow on the control panel login page, for example, you get distinct messages saying if the username/email didn't exist or the email was successfully sent and to check your email for further instructions.
privateTemplateTrigger string – The template path segment prefix that should be used to identify "private" templates (templates that aren't directly accessible via a matching URL).
purgePendingUsersDuration mixed – The amount of time to wait before Craft purges pending users from the system that have not activated.
purgeStaleUserSessionDuration mixed – The amount of time to wait before Craft purges stale user sessions from the sessions table in the database.
purgeUnsavedDraftsDuration mixed – The amount of time to wait before Craft purges drafts of new elements that were never formally saved.
rememberUsernameDuration mixed – The amount of time Craft will remember a username and pre-populate it on the control panel’s Login page.
rememberedUserSessionDuration mixed – The amount of time a user stays logged if “Remember Me” is checked on the login page.
requireMatchingUserAgentForSession boolean – Whether Craft should require a matching user agent string when restoring a user session from a cookie.
requireUserAgentAndIpForSession boolean – Whether Craft should require the existence of a user agent string and IP address when creating a new user session.
resourceBasePath string – The path to the root directory that should store published control panel resources.
resourceBaseUrl string – The URL to the root directory that should store published control panel resources.
restoreCommand string, null – The shell command that Craft should execute to restore a database backup.
rotateImagesOnUploadByExifData boolean – Whether Craft should rotate images according to their EXIF data on upload.
runQueueAutomatically boolean – Whether Craft should run pending queue jobs automatically when someone visits the control panel.
sameSiteCookieValue string – The [SameSite](https://www.
sanitizeSvgUploads boolean – Whether Craft should sanitize uploaded SVG files and strip out potential malicious looking content.
secureHeaders array, null – Lists of headers that are, by default, subject to the trusted host configuration.
secureProtocolHeaders array, null – List of headers to check for determining whether the connection is made via HTTPS.
securityKey string – A private, random, cryptographically-secure key that is used for hashing and encrypting data in craft\services\Security.
sendPoweredByHeader boolean – Whether an X-Powered-By: Craft CMS header should be sent, helping services like [BuiltWith](https://builtwith.
setPasswordPath mixed – The URI Craft should use for Set Password forms on the front-end.
setPasswordSuccessPath mixed – The URI Craft should redirect users to after setting their password from the front-end.
siteName string, string[] – The site name(s).
siteUrl string, string[] – The base URL to the site(s).
slugWordSeparator string – The character(s) that should be used to separate words in slugs.
softDeleteDuration mixed – The amount of time before a soft-deleted item will be up for hard-deletion by garbage collection.
storeUserIps boolean – Whether user IP addresses should be stored/logged by the system.
suppressTemplateErrors boolean – Whether Twig runtime errors should be suppressed.
testToEmailAddress string, array, false, null – Configures Craft to send all system emails to a single email address, or an array of email addresses for testing purposes.
timezone string, null – The timezone of the site.
tokenParam string – The query string parameter name that Craft tokens should be set to.
transformGifs boolean – Whether GIF files should be cleansed/transformed.
translationDebugOutput boolean – Whether translated messages should be wrapped in special characters, to help find any strings that are not being run through Craft::t() or the |translate filter.
trustedHosts array – The configuration for trusted security-related headers.
upscaleImages boolean – Whether images should be upscaled if the provided transform size is larger than the image.
useCompressedJs boolean – Whether Craft should include minified JavaScript files whenever possible, and minify JavaScript code passed to \craft\web\View::includeJs() or {% js %} Twig tags.
useEmailAsUsername boolean – Whether Craft should set users’ usernames to their email addresses, rather than let them set their username separately.
useFileLocks boolean, null – Whether to grab an exclusive lock on a file when writing to it by using the LOCK_EX flag.
usePathInfo boolean – Whether Craft should specify the path using PATH_INFO or as a query string parameter when generating URLs.
useProjectConfigFile boolean – Whether the project config should be saved out to `config/project.
useSecureCookies boolean, string – Whether Craft will set the "secure" flag when saving cookies when using Craft::cookieConfig() to create a cookie.
useSslOnTokenizedUrls boolean, string – Determines what protocol/schema Craft will use when generating tokenized URLs.
userSessionDuration mixed – The amount of time before a user will get logged out due to inactivity.
verificationCodeDuration mixed – The amount of time a user verification code can be used before expiring.
verifyEmailPath mixed – The URI Craft should use for email verification links on the front-end.
verifyEmailSuccessPath mixed – The URI that users without access to the control panel should be redirected to after verifying a new email address.

# actionTrigger

Type
string

The URI segment Craft should look for when determining if the current request should be routed to a controller action.

View source

# activateAccountSuccessPath

Type
mixed

The URI that users without access to the control panel should be redirected to after activating their account.

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

See also getActivateAccountSuccessPath()

View source

# addTrailingSlashesToUrls

Type
boolean

Whether auto-generated URLs should have trailing slashes.

View source

# aliases

Type
array

Any custom Yii aliases that should be defined for every request.

View source

# allowAdminChanges

Type
boolean
Since
3.1.0

Whether admins should be allowed to make administrative changes to the system.

If this is disabled, the Settings and Plugin Store sections will be hidden, the Craft edition and Craft/plugin versions will be locked, and the project config will become read-only.

Therefore you should only disable this in production environments when useProjectConfigFile is enabled, and you have a deployment workflow that runs composer install automatically on deploy.

WARNING

Don’t disable this setting until all environments have been updated to Craft 3.1.0 or later.

View source

# allowSimilarTags

Type
boolean

Whether users should be allowed to create similarly-named tags.

View source

# allowUpdates

Type
boolean

Whether Craft should allow system and plugin updates in the control panel, and plugin installation from the Plugin Store.

This setting will automatically be disabled if allowAdminChanges is disabled.

View source

# allowUppercaseInSlug

Type
boolean

Whether uppercase letters should be allowed in slugs.

View source

# allowedFileExtensions

Type
string[]

The file extensions Craft should allow when a user is uploading files.

See also extraAllowedFileExtensions

View source

# autoLoginAfterAccountActivation

Type
boolean

Whether users should automatically be logged in after activating their account or resetting their password.

View source

# backupCommand

Type
string, null

The shell command that Craft should execute to create a database backup.

By default Craft will run mysqldump or pg_dump, provided that those libraries are in the $PATH variable for the user the web server is running as.

There are several tokens you can use that Craft will swap out at runtime:

  • {path} - the target backup file path
  • {port} - the current database port
  • {server} - the current database host name
  • {user} - the user to connect to the database
  • {database} - the current database name
  • {schema} - the current database schema (if any)

This can also be set to false to disable database backups completely.

View source

# backupOnUpdate

Type
boolean

Whether Craft should create a database backup before applying a new system update.

See also backupCommand

View source

# baseCpUrl

Type
string, null

The base URL that Craft should use when generating control panel URLs.

It will be determined automatically if left blank.

TIP

The base control panel URL should not include the control panel trigger word (e.g. /admin).

View source

# blowfishHashCost

Type
integer

The higher the cost value, the longer it takes to generate a password hash and to verify against it. Therefore, higher cost slows down a brute-force attack.

For best protection against brute force attacks, set it to the highest value that is tolerable on production servers.

The time taken to compute the hash doubles for every increment by one for this value. For example, if the hash takes 1 second to compute when the value is 14 then the compute time varies as 2^(value - 14) seconds.

View source

# cacheDuration

Type
mixed

The default length of time Craft will store data, RSS feed, and template caches.

If set to 0, data and RSS feed caches will be stored indefinitely; template caches will be stored for one year.

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

View source

# cacheElementQueries

Type
boolean

Whether Craft should cache element queries that fall inside {% cache %} tags.

View source

# convertFilenamesToAscii

Type
boolean

Whether uploaded filenames with non-ASCII characters should be converted to ASCII (i.e. ñn).

TIP

You can run ./craft utils/ascii-filenames in your terminal to apply ASCII filenames to all existing assets.

View source

# cooldownDuration

Type
mixed

The amount of time a user must wait before re-attempting to log in after their account is locked due to too many failed login attempts.

Set to 0 to keep the account locked indefinitely, requiring an admin to manually unlock the account.

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

View source

# cpTrigger

Type
string

The URI segment Craft should look for when determining if the current request should route to the control panel rather than the front-end website.

View source

# csrfTokenName

Type
string

The name of CSRF token used for CSRF validation if enableCsrfProtection is set to true.

See also enableCsrfProtection

View source

# customAsciiCharMappings

DEPRECATED

Deprecated in 3.0.10. Any corrections to ASCII char mappings should be submitted to Stringy.

Type
array

Any custom ASCII character mappings.

This array is merged into the default one in StringHelper::asciiCharMap(). The key is the ASCII character to be used for the replacement and the value is an array of non-ASCII characters that the key maps to.

View source

Example

'customAsciiCharMappings' => [
    'c' => ['ç', 'ć', 'č', 'ĉ', 'ċ'],
],

# defaultCookieDomain

Type
string

The domain that cookies generated by Craft should be created for. If blank, it will be left up to the browser to determine which domain to use (almost always the current). If you want the cookies to work for all subdomains, for example, you could set this to '.domain.com'.

View source

# defaultCpLanguage

Type
string, null

The default language the control panel should use for users who haven’t set a preferred language yet.

View source

# defaultDirMode

Type
mixed

The default permission to be set for newly generated directories.

If set to null, the permission will be determined by the current environment.

View source

# defaultFileMode

Type
integer, null

The default permission to be set for newly generated files.

If set to null, the permission will be determined by the current environment.

View source

# defaultImageQuality

Type
integer

The quality level Craft will use when saving JPG and PNG files. Ranges from 0 (worst quality, smallest file) to 100 (best quality, biggest file).

View source

# defaultSearchTermOptions

Type
array

The default options that should be applied to each search term.

Options include:

  • attribute – The attribute that the term should apply to (e.g. 'title'), if any. (null by default)
  • exact – Whether the term must be an exact match (only applies if attribute is set). (false by default)
  • exclude – Whether search results should exclude records with this term. (false by default)
  • subLeft – Whether to include keywords that contain the term, with additional characters before it. (false by default)
  • subRight – Whether to include keywords that contain the term, with additional characters after it. (true by default)

View source

# defaultTemplateExtensions

Type
string[]

The template file extensions Craft will look for when matching a template path to a file on the front end.

View source

# defaultTokenDuration

Type
mixed

The default amount of time tokens can be used before expiring.

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

View source

# defaultWeekStartDay

Type
integer

The default day that new users should have set as their Week Start Day.

This should be set to one of the following integers:

  • 0 – Sunday
  • 1 – Monday
  • 2 – Tuesday
  • 3 – Wednesday
  • 4 – Thursday
  • 5 – Friday
  • 6 – Saturday

View source

# deferPublicRegistrationPassword

Type
boolean

By default, Craft will require a 'password' field to be submitted on front-end, public user registrations. Setting this to true will no longer require it on the initial registration form.

If you have email verification enabled, new users will set their password once they've clicked on the verification link in the email. If you don't, the only way they can set their password is to go through your "forgot password" workflow.

View source

# devMode

Type
boolean

Whether the system should run in Dev Mode.

View source

# disabledPlugins

Type
string[]
Since
3.1.9

Array of plugin handles that should be disabled, regardless of what the project config says.

View source

Example

'dev' => [
    'disabledPlugins' => ['webhooks'],
],

# elevatedSessionDuration

Type
mixed

The amount of time a user’s elevated session will last, which is required for some sensitive actions (e.g. user group/permission assignment).

Set to 0 to disable elevated session support.

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

View source

# enableCsrfCookie

Type
boolean

Whether to use a cookie to persist the CSRF token if enableCsrfProtection is enabled. If false, the CSRF token will be stored in session under the csrfTokenName config setting name. Note that while storing CSRF tokens in session increases security, it requires starting a session for every page that a CSRF token is needed, which may degrade site performance.

See also enableCsrfProtection

View source

# enableCsrfProtection

Type
boolean

Whether to enable CSRF protection via hidden form inputs for all forms submitted via Craft.

See also:

View source

# enableGql

Type
boolean
Since
3.3.1

Whether the GraphQL API should be enabled.

Note that the GraphQL API is only available for Craft Pro.

View source

# enableGraphQlCaching

Type
boolean
Since
3.3.12

Whether Craft should cache GraphQL queries.

If set to true, Craft will cache the results for unique GraphQL queries per access token. The cache is automatically invalidated any time an element is saved, the site structure is updated, or a GraphQL schema is saved.

This setting will have no effect if a plugin is using the craft\services\Gql::EVENT_BEFORE_EXECUTE_GQL_QUERY event to provide its own caching logic and setting the result property.

View source

# enableTemplateCaching

Type
boolean

Whether to enable Craft's template {% cache %} tag on a global basis.

See also http://craftcms.com/docs/templating/cache

View source

# errorTemplatePrefix

Type
string

The prefix that should be prepended to HTTP error status codes when determining the path to look for an error’s template.

If set to '_', then your site’s 404 template would live at templates/_404.html, for example.

View source

# extraAllowedFileExtensions

Type
string[], null

List of file extensions that will be merged into the allowedFileExtensions config setting.

See also allowedFileExtensions

View source

# extraAppLocales

Type
string[], null
Since
3.0.24

List of extra locale IDs that the application should support, and users should be able to select as their Preferred Language.

Only use this setting if your server has the Intl PHP extension, or if you’ve saved the corresponding locale data into your config/locales/ folder.

View source

# extraFileKinds

Type
array
Since
3.0.37

List of additional file kinds Craft should support. This array will get merged with the one defined in \craft\helpers\Assets::_buildFileKinds().

'extraFileKinds' => [
    // merge .psb into list of Photoshop file kinds
    'photoshop' => [
        'extensions' => ['psb'],
    ],
    // register new "Stylesheet" file kind
    'stylesheet' => [
        'label' => 'Stylesheet',
        'extensions' => ['css', 'less', 'pcss', 'sass', 'scss', 'styl'],
    ],
],

TIP

File extensions listed here won’t immediately be allowed to be uploaded. You will also need to list them with the extraAllowedFileExtensions config setting.

View source

# filenameWordSeparator

Type
string, boolean

The string to use to separate words when uploading Assets. If set to false, spaces will be left alone.

View source

# generateTransformsBeforePageLoad

Type
boolean

Whether images transforms should be generated before page load.

View source

# headlessMode

Type
boolean
Since
3.3.0

Bool Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations.

When this is enabled, the following changes will take place:

  • Template settings for sections and category groups will be hidden.
  • Template route management will be hidden.
  • Front-end routing will skip checks for element and template requests.
  • Front-end responses will be JSON-formatted rather than HTML by default.
  • Twig will be configured to escape unsafe strings for JavaScript/JSON rather than HTML by default for front-end requests.
  • The loginPath, logoutPath, setPasswordPath, and verifyEmailPath settings will be ignored.

View source

# imageDriver

Type
mixed

The image driver Craft should use to cleanse and transform images. By default Craft will auto-detect if ImageMagick is installed and fallback to GD if not. You can explicitly set either 'imagick' or 'gd' here to override that behavior.

View source

# indexTemplateFilenames

Type
string[]

The template filenames Craft will look for within a directory to represent the directory’s “index” template when matching a template path to a file on the front end.

View source

# invalidLoginWindowDuration

Type
mixed

The amount of time to track invalid login attempts for a user, for determining if Craft should lock an account.

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

View source

# invalidUserTokenPath

Type
mixed

The URI Craft should redirect to when user token validation fails. A token is used on things like setting and resetting user account passwords. Note that this only affects front-end site requests.

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

See also getInvalidUserTokenPath()

View source

# ipHeaders

Type
string[], null

List of headers where proxies store the real client IP.

See yii\web\Request::$ipHeaders for more details.

If not set, the default craft\web\Request::$ipHeaders value will be used.

View source

# isSystemLive

Type
boolean, null

Whether the site is currently live. If set to true or false, it will take precedence over the System Status setting in Settings → General.

View source

# limitAutoSlugsToAscii

Type
boolean

Whether non-ASCII characters in auto-generated slugs should be converted to ASCII (i.e. ñ → n).

TIP

This only affects the JavaScript auto-generated slugs. Non-ASCII characters can still be used in slugs if entered manually.

View source

# loginPath

Type
mixed

The URI Craft should use for user login on the front-end.

This can be set to false to disable front-end login.

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

See also getLoginPath()

View source

# logoutPath

Type
mixed

The URI Craft should use for user logout on the front-end.

This can be set to false to disable front-end logout.

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

See also getLogoutPath()

View source

# maxBackups

Type
integer, false

The number of backups that Craft should make before it starts deleting the oldest backups. If it is set to false, then Craft will not delete any backups.

View source

# maxCachedCloudImageSize

Type
integer

The maximum dimension size to use when caching images from external sources to use in transforms. Set to 0 to never cache them.

View source

# maxInvalidLogins

Type
integer

The number of invalid login attempts Craft will allow within the specified duration before the account gets locked.

View source

# maxRevisions

Type
integer, null
Since
3.2.0

The maximum number of revisions that should be stored for each element.

Set to 0 if you want to store an unlimited number of revisions.

View source

# maxSlugIncrement

Type
integer

The highest number Craft will tack onto a slug in order to make it unique before giving up and throwing an error.

View source

# maxUploadFileSize

Type
integer, string

The maximum upload file size allowed.

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

View source

# omitScriptNameInUrls

Type
boolean

Whether generated URLs should omit index.php (e.g. http://domain.com/path instead of http://domain.com/index.php/path)

This can only be possible if your server is configured to redirect would-be 404's to index.php, for example, with the redirect found in the .htaccess file that came with Craft:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule (.+) /index.php?p=$1 [QSA,L]

View source

# optimizeImageFilesize

Type
boolean

Whether Craft should optimize images for reduced file sizes without noticeably reducing image quality. (Only supported when ImageMagick is used.)

See also imageDriver

View source

# pageTrigger

Type
string

The string preceding a number which Craft will look for when determining if the current request is for a particular page in a paginated list of pages.

Example Value Example URI
p /news/p5
page /news/page5
page/ /news/page/5
?page /news?page=5

TIP

If you want to set this to ?p (e.g. /news?p=5), you will need to change your pathParam setting as well, which is set to p by default, and if your server is running Apache, you will need to update the redirect code in your .htaccess file to match your new pathParam value.

See also getPageTrigger()

View source

# pathParam

Type
string

The query string param that Craft will check when determining the request's path.

TIP

If you change this and your server is running Apache, don’t forget to update the redirect code in your .htaccess file to match the new value.

View source

# phpMaxMemoryLimit

Type
string, null

The maximum amount of memory Craft will try to reserve during memory intensive operations such as zipping, unzipping and updating. Defaults to an empty string, which means it will use as much memory as it possibly can.

See http://php.net/manual/en/faq.using.php#faq.using.shorthandbytes for a list of acceptable values.

View source

# phpSessionName

Type
string

The name of the PHP session cookie.

See also https://php.net/manual/en/function.session-name.php

View source

# postCpLoginRedirect

Type
mixed

The path that users should be redirected to after logging in from the control panel.

This setting will also come into effect if a user visits the control panel’s Login page (/admin/login) or the control panel’s root URL (/admin) when they are already logged in.

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

See also getPostCpLoginRedirect()

View source

# postLoginRedirect

Type
mixed

The path that users should be redirected to after logging in from the front-end site.

This setting will also come into effect if the user visits the Login page (as specified by the loginPath config setting) when they are already logged in.

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

See also getPostLoginRedirect()

View source

# postLogoutRedirect

Type
mixed

The path that users should be redirected to after logging out from the front-end site.

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

See also getPostLogoutRedirect()

View source

# preserveCmykColorspace

Type
boolean
Since
3.0.8

Whether CMYK should be preserved as the colorspace when manipulating images.

Setting this to true will prevent Craft from transforming CMYK images to sRGB, but on some ImageMagick versions it can cause color distortion in the image. This will only have effect if ImageMagick is in use.

View source

# preserveExifData

Type
boolean

Whether the EXIF data should be preserved when manipulating and uploading images.

Setting this to true will result in larger image file sizes.

This will only have effect if ImageMagick is in use.

View source

# preserveImageColorProfiles

Type
boolean

Whether the embedded Image Color Profile (ICC) should be preserved when manipulating images.

Setting this to false will reduce the image size a little bit, but on some ImageMagick versions can cause images to be saved with an incorrect gamma value, which causes the images to become very dark. This will only have effect if ImageMagick is in use.

View source

# preventUserEnumeration

Type
boolean

When set to false and you go through the "forgot password" workflow on the control panel login page, for example, you get distinct messages saying if the username/email didn't exist or the email was successfully sent and to check your email for further instructions. This can allow for username/email enumeration based on the response. If set true, you will always get a successful response even if there was an error making it difficult to enumerate users.

View source

# privateTemplateTrigger

Type
string

The template path segment prefix that should be used to identify "private" templates (templates that aren't directly accessible via a matching URL).

Set to an empty value to disable public template routing.

View source

# purgePendingUsersDuration

Type
mixed

The amount of time to wait before Craft purges pending users from the system that have not activated.

Note that any content assigned to a pending user will be deleted as well when the given time interval passes.

Set to 0 to disable this feature.

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

View source

# purgeStaleUserSessionDuration

Type
mixed
Since
3.3.0

The amount of time to wait before Craft purges stale user sessions from the sessions table in the database.

Set to 0 to disable this feature.

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

View source

# purgeUnsavedDraftsDuration

Type
mixed
Since
3.2.0

The amount of time to wait before Craft purges drafts of new elements that were never formally saved.

Set to 0 to disable this feature.

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

View source

# rememberUsernameDuration

Type
mixed

The amount of time Craft will remember a username and pre-populate it on the control panel’s Login page.

Set to 0 to disable this feature altogether.

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

View source

# rememberedUserSessionDuration

Type
mixed

The amount of time a user stays logged if “Remember Me” is checked on the login page.

Set to 0 to disable the “Remember Me” feature altogether.

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

View source

# requireMatchingUserAgentForSession

Type
boolean

Whether Craft should require a matching user agent string when restoring a user session from a cookie.

View source

# requireUserAgentAndIpForSession

Type
boolean

Whether Craft should require the existence of a user agent string and IP address when creating a new user session.

View source

# resourceBasePath

Type
string

The path to the root directory that should store published control panel resources.

View source

# resourceBaseUrl

Type
string

The URL to the root directory that should store published control panel resources.

View source

# restoreCommand

Type
string, null

The shell command that Craft should execute to restore a database backup.

By default Craft will run mysql or psql, provided that those libraries are in the $PATH variable for the user the web server is running as.

There are several tokens you can use that Craft will swap out at runtime:

  • {path} - the backup file path
  • {port} - the current database port
  • {server} - the current database host name
  • {user} - the user to connect to the database
  • {database} - the current database name
  • {schema} - the current database schema (if any)

This can also be set to false to disable database restores completely.

View source

# rotateImagesOnUploadByExifData

Type
boolean

Whether Craft should rotate images according to their EXIF data on upload.

View source

# runQueueAutomatically

Type
boolean

Whether Craft should run pending queue jobs automatically when someone visits the control panel.

If disabled, an alternate queue worker must be set up separately, either as an always-running daemon, or a cron job that runs the queue/run command every minute:

* * * * * /path/to/project/craft queue/run

TIP

This setting should be disabled for servers running Win32, or with Apache’s mod_deflate/mod_gzip installed, where PHP’s flush() method won’t work.

View source

# sameSiteCookieValue

Type
string
Since
3.1.33

The SameSite value that should be set on Craft cookies, if any.

This can be set to 'Lax', 'Strict', or null.

TIP

This setting requires PHP 7.3 or later.

View source

# sanitizeSvgUploads

Type
boolean

Whether Craft should sanitize uploaded SVG files and strip out potential malicious looking content.

This should definitely be enabled if you are accepting SVG uploads from untrusted sources.

View source

# secureHeaders

Type
array, null

Lists of headers that are, by default, subject to the trusted host configuration.

See yii\web\Request::$secureHeaders for more details.

If not set, the default yii\web\Request::$secureHeaders value will be used.

View source

# secureProtocolHeaders

Type
array, null

List of headers to check for determining whether the connection is made via HTTPS.

See yii\web\Request::$secureProtocolHeaders for more details.

If not set, the default yii\web\Request::$secureProtocolHeaders value will be used.

View source

# securityKey

Type
string

A private, random, cryptographically-secure key that is used for hashing and encrypting data in craft\services\Security.

This value should be the same across all environments. Note that if this key ever changes, any data that was encrypted with it will be inaccessible.

View source

# sendPoweredByHeader

Type
boolean

Whether an X-Powered-By: Craft CMS header should be sent, helping services like BuiltWith and Wappalyzer identify that the site is running on Craft.

View source

# setPasswordPath

Type
mixed

The URI Craft should use for Set Password forms on the front-end.

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

TIP

You might also want to set invalidUserTokenPath in case a user clicks on an expired password reset link.

See also getSetPasswordPath()

View source

# setPasswordSuccessPath

Type
mixed

The URI Craft should redirect users to after setting their password from the front-end.

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

See also getSetPasswordSuccessPath()

View source

# siteName

Type
string, string[]

The site name(s). If set, it will take precedence over the Name settings in Settings → Sites → [Site Name].

This can be set to a string, which will override the primary site’s name only, or an array with site handles used as the keys.

View source

# siteUrl

Type
string, string[]

The base URL to the site(s). If set, it will take precedence over the Base URL settings in Settings → Sites → [Site Name].

This can be set to a string, which will override the primary site’s base URL only, or an array with site handles used as the keys.

The URL(s) must begin with either http://, https://, // (protocol-relative), or an alias.

'siteUrl' => [
    'siteA' => 'https://site-a.com/',
    'siteB' => 'https://site-b.com/',
],

View source

# slugWordSeparator

Type
string

The character(s) that should be used to separate words in slugs.

View source

# softDeleteDuration

Type
mixed
Since
3.1.0

The amount of time before a soft-deleted item will be up for hard-deletion by garbage collection.

Set to 0 if you don’t ever want to delete soft-deleted items.

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

View source

# storeUserIps

Type
boolean
Since
3.1.0

Whether user IP addresses should be stored/logged by the system.

View source

# suppressTemplateErrors

DEPRECATED

Deprecated in 3.3.0

Type
boolean

Whether Twig runtime errors should be suppressed.

If it is set to true, the errors will still be logged to Craft’s log files.

View source

# testToEmailAddress

Type
string, array, false, null

Configures Craft to send all system emails to a single email address, or an array of email addresses for testing purposes.

By default the recipient name(s) will be “Test Recipient”, but you can customize that by setting the value with the format ['email@address.com' => 'Name'].

View source

# timezone

Type
string, null

The timezone of the site. If set, it will take precedence over the Timezone setting in Settings → General.

This can be set to one of PHP’s supported timezones.

View source

# tokenParam

Type
string

The query string parameter name that Craft tokens should be set to.

View source

# transformGifs

Type
boolean
Since
3.0.7

Whether GIF files should be cleansed/transformed.

View source

# translationDebugOutput

Type
boolean

Whether translated messages should be wrapped in special characters, to help find any strings that are not being run through Craft::t() or the |translate filter.

View source

# trustedHosts

Type
array

The configuration for trusted security-related headers.

See yii\web\Request::$trustedHosts for more details.

By default, all hosts are trusted.

View source

# upscaleImages

Type
boolean
Since
3.4.0

Whether images should be upscaled if the provided transform size is larger than the image.

View source

# useCompressedJs

Type
boolean

Whether Craft should include minified JavaScript files whenever possible, and minify JavaScript code passed to \craft\web\View::includeJs() or {% js %} Twig tags.

View source

# useEmailAsUsername

Type
boolean

Whether Craft should set users’ usernames to their email addresses, rather than let them set their username separately.

View source

# useFileLocks

Type
boolean, null

Whether to grab an exclusive lock on a file when writing to it by using the LOCK_EX flag.

Some file systems, such as NFS, do not support exclusive file locking.

If not set to true or false, Craft will automatically try to detect if the underlying file system supports exclusive file locking and cache the results.

See also http://php.net/manual/en/function.file-put-contents.php

View source

# usePathInfo

Type
boolean

Whether Craft should specify the path using PATH_INFO or as a query string parameter when generating URLs.

Note that this setting only takes effect if omitScriptNameInUrls is set to false.

View source

# useProjectConfigFile

Type
boolean
Since
3.1.0

Whether the project config should be saved out to config/project.yaml.

If set to true, a hard copy of your system’s project config will be saved in config/project.yaml, and any changes to config/project.yaml will be applied back to the system, making it possible for multiple environments to share the same project config despite having separate databases.

WARNING

Make sure you’ve read the entire Project Config documentation, and carefully follow the “Enabling the Project Config File” steps when enabling this setting.

View source

# useSecureCookies

Type
boolean, string

Whether Craft will set the "secure" flag when saving cookies when using Craft::cookieConfig() to create a cookie.

Valid values are true, false, and 'auto'. Defaults to 'auto', which will set the secure flag if the page you're currently accessing is over https://. true will always set the flag, regardless of protocol and false will never automatically set the flag.

View source

# useSslOnTokenizedUrls

Type
boolean, string

Determines what protocol/schema Craft will use when generating tokenized URLs. If set to 'auto', Craft will check the siteUrl and the protocol of the current request and if either of them are https will use https in the tokenized URL. If not, will use http.

If set to false, the Craft will always use http. If set to true, then, Craft will always use https.

View source

# userSessionDuration

Type
mixed

The amount of time before a user will get logged out due to inactivity.

Set to 0 if you want users to stay logged in as long as their browser is open rather than a predetermined amount of time.

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

View source

# verificationCodeDuration

Type
mixed

The amount of time a user verification code can be used before expiring.

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

View source

# verifyEmailPath

Type
mixed
Since
3.4.0

The URI Craft should use for email verification links on the front-end.

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

See also getVerifyEmailPath()

View source

# verifyEmailSuccessPath

Type
mixed
Since
3.1.20

The URI that users without access to the control panel should be redirected to after verifying a new email address.

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

See also getVerifyEmailSuccessPath()

View source

# Public Methods

Method Description
__call() Calls the named method which is not a class method.
__construct() Constructor.
__get() Returns the value of an object property.
__isset() Checks if a property is set, i.e. defined and not null.
__set() Sets value of an object property.
__unset() Sets an object property to null.
canGetProperty() Returns a value indicating whether a property can be read.
canSetProperty() Returns a value indicating whether a property can be set.
className() Returns the fully qualified name of this class.
getActivateAccountSuccessPath() Returns the localized Activate Account Success Path value.
getBackupOnUpdate() Returns whether the DB should be backed up before running new migrations.
getInvalidUserTokenPath() Returns the localized Invalid User Token Path value.
getLoginPath() Returns the localized Login Path value.
getLogoutPath() Returns the localized Logout Path value.
getPageTrigger() Returns the normalized page trigger.
getPostCpLoginRedirect() Returns the localized Post-Login Redirect path for the control panel.
getPostLoginRedirect() Returns the localized Post-Login Redirect path.
getPostLogoutRedirect() Returns the localized Post-Logout Redirect path.
getSetPasswordPath() Returns the localized Set Password Path value.
getSetPasswordSuccessPath() Returns the localized Set Password Success Path value.
getVerifyEmailPath() Returns the localized Verify Email Path value.
getVerifyEmailSuccessPath() Returns the localized Verify Email Success Path value.
hasMethod() Returns a value indicating whether a method is defined.
hasProperty() Returns a value indicating whether a property is defined.
init() Initializes the object.

# __construct()

Constructor.

The default implementation does two things:

  • Initializes the object with the given configuration $config.
  • Call init().

If this method is overridden in a child class, it is recommended that

  • the last parameter of the constructor is a configuration array, like $config here.
  • call the parent implementation at the end of the constructor.

View source

Arguments

  • $config (array) – Name-value pairs that will be used to initialize the object properties

# __get()

Returns the value of an object property.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $value = $object->property;.

View source

Arguments

  • $name (string) – The property name

Returns

mixed – The property value

Throws

# __isset()

Checks if a property is set, i.e. defined and not null.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing isset($object->property).

Note that if the property is not defined, false will be returned.

View source

Arguments

  • $name (string) – The property name or the event name

Returns

boolean – Whether the named property is set (not null).

# __set()

Sets value of an object property.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $object->property = $value;.

View source

Arguments

  • $name (string) – The property name or the event name
  • $value (mixed) – The property value

Throws

# getActivateAccountSuccessPath()

Returns the localized Activate Account Success Path value.

See also activateAccountSuccessPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# getBackupOnUpdate()

Returns whether the DB should be backed up before running new migrations.

View source

Returns

boolean

# getInvalidUserTokenPath()

Returns the localized Invalid User Token Path value.

See also invalidUserTokenPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# getLoginPath()

Returns the localized Login Path value.

See also loginPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

mixed

# getLogoutPath()

Returns the localized Logout Path value.

See also logoutPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

mixed

# getPageTrigger()

Since
3.2.0

Returns the normalized page trigger.

See also pageTrigger View source

Returns

string

# getPostCpLoginRedirect()

Returns the localized Post-Login Redirect path for the control panel.

See also postCpLoginRedirect View source

Returns

string

# getPostLoginRedirect()

Returns the localized Post-Login Redirect path.

See also postLoginRedirect View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# getPostLogoutRedirect()

Returns the localized Post-Logout Redirect path.

See also postLogoutRedirect View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# getSetPasswordPath()

Returns the localized Set Password Path value.

See also setPasswordPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# getSetPasswordSuccessPath()

Returns the localized Set Password Success Path value.

See also setPasswordSuccessPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# getVerifyEmailPath()

Since
3.4.0

Returns the localized Verify Email Path value.

See also verifyEmailPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# getVerifyEmailSuccessPath()

Since
3.1.20

Returns the localized Verify Email Success Path value.

See also verifyEmailSuccessPath View source

Arguments

  • $siteHandle (string, null) – The site handle the value should be defined for. Defaults to the current site.

Returns

string

# init()

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

View source

# Constants

Constant Description
IMAGE_DRIVER_AUTO
IMAGE_DRIVER_GD
IMAGE_DRIVER_IMAGICK