General Settings

This group of settings affects a wide variety of Craft’s features and behaviors. If you are uncertain about whether something is configurable or not, refer to the categories in the table of contents.

General settings go in config/general.php. The config file that ships with new Craft projects (opens new window) looks like this:

use craft\config\GeneralConfig;
use craft\helpers\App;

return GeneralConfig::create()
    ->defaultWeekStartDay(1)
    ->omitScriptNameInUrls()
    ->devMode(App::env('DEV_MODE') ?? false)
    ->allowAdminChanges(App::env('ALLOW_ADMIN_CHANGES') ?? false)
    ->disallowRobots(App::env('DISALLOW_ROBOTS') ?? false)

There are a number of ways to provide configuration. This file uses the new “fluent” syntax, and contains references to environment variables for settings that may change between environments.

# System

# accessibilityDefaults

Allowed types
array (opens new window)
Default value
[ 'alwaysShowFocusRings' => false, 'useShapes' => false, 'underlineLinks' => false, 'disableAutofocus' => false, 'notificationDuration' => 5000, ]
Defined by
GeneralConfig::$accessibilityDefaults (opens new window)
Since
3.6.4

The default user accessibility preferences that should be applied to users that haven’t saved their preferences yet.

The array can contain the following keys:

  • alwaysShowFocusRings - Whether focus rings should always be shown when an element has focus.
  • useShapes – Whether shapes should be used to represent statuses.
  • underlineLinks – Whether links should be underlined.
  • notificationDuration – How long notifications should be shown before they disappear automatically (in milliseconds). Set to 0 to show them indefinitely.
->accessibilityDefaults([
    'useShapes' => true,
])

# allowAdminChanges

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$allowAdminChanges (opens new window)
Since
3.1.0

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

When this is disabled, the Settings section will be hidden, the Craft edition and Craft/plugin versions will be locked, and the project config and Plugin Store will become read-only—though Craft and plugin licenses may still be purchased.

It’s best to disable this in production environments with a deployment workflow that runs composer install and propagates project config updates on deploy.

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

->allowAdminChanges(false)

# allowSimilarTags

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$allowSimilarTags (opens new window)

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

->allowSimilarTags(true)

# allowUpdates

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$allowUpdates (opens new window)

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.

->allowUpdates(false)

# autoLoginAfterAccountActivation

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$autoLoginAfterAccountActivation (opens new window)

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

->autoLoginAfterAccountActivation(true)

# autosaveDrafts

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$autosaveDrafts (opens new window)
Since
3.5.6
Deprecated
in 4.0.0

Whether drafts should be saved automatically as they are edited.

Note that drafts will be autosaved while Live Preview is open, regardless of this setting.

CRAFT_AUTOSAVE_DRAFTS=false

# backupOnUpdate

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$backupOnUpdate (opens new window)

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

->backupOnUpdate(false)

# cacheDuration

Allowed types
mixed
Default value
86400 (1 day)
Defined by
GeneralConfig::$cacheDuration (opens new window)

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() (opens new window) for a list of supported value types.

->cacheDuration(0)

# cpHeadTags

Allowed types
array (opens new window)
Default value
[]
Defined by
GeneralConfig::$cpHeadTags (opens new window)
Since
3.5.0

List of additional HTML tags that should be included in the <head> of control panel pages.

Each tag can be specified as an array of the tag name and its attributes.

For example, you can give the control panel a custom favicon (etc.) like this:

->cpHeadTags([
    // Traditional favicon
    ['link', ['rel' => 'icon', 'href' => '/icons/favicon.ico']],
    // Scalable favicon for browsers that support them
    ['link', ['rel' => 'icon', 'type' => 'image/svg+xml', 'sizes' => 'any', 'href' => '/icons/favicon.svg']],
    // Touch icon for mobile devices
    ['link', ['rel' => 'apple-touch-icon', 'sizes' => '180x180', 'href' => '/icons/touch-icon.svg']],
    // Pinned tab icon for Safari
    ['link', ['rel' => 'mask-icon', 'href' => '/icons/mask-icon.svg', 'color' => '#663399']],
])

# defaultCountryCode

Allowed types
string (opens new window)
Default value
'US'
Defined by
GeneralConfig::$defaultCountryCode (opens new window)
Since
4.5.0

The two-letter country code that addresses will be set to by default.

See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 (opens new window) for a list of acceptable country codes.

->defaultCountryCode('GB')

# defaultCpLanguage

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$defaultCpLanguage (opens new window)

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

->defaultCpLanguage('en-US')

# defaultCpLocale

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$defaultCpLocale (opens new window)
Since
3.5.0

The default locale the control panel should use for date/number formatting, for users who haven’t set a preferred language or formatting locale.

If this is null, the defaultCpLanguage config setting will determine which locale is used for date/number formatting by default.

->defaultCpLocale('en-US')

# defaultDirMode

Allowed types
mixed
Default value
0775
Defined by
GeneralConfig::$defaultDirMode (opens new window)

The default permission to be set for newly-generated directories.

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

->defaultDirMode(0744)

# defaultFileMode

Allowed types
integer (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$defaultFileMode (opens new window)

The default permission to be set for newly-generated files.

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

->defaultFileMode(0744)

# defaultSearchTermOptions

Allowed types
array (opens new window)
Default value
[]
Defined by
GeneralConfig::$defaultSearchTermOptions (opens new window)

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

Options include:

  • 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)
  • exclude – Whether search results should exclude records with this term. (false by default)
  • exact – Whether the term must be an exact match (only applies if the search term specifies an attribute). (false by default)
->defaultSearchTermOptions([
    'subLeft' => true,
    'exclude' => 'secret',
])

# defaultTemplateExtensions

Allowed types
string (opens new window)[]
Default value
[ 'twig', 'html', ]
Defined by
GeneralConfig::$defaultTemplateExtensions (opens new window)

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

->defaultTemplateExtensions(['twig', 'html', 'txt'])

# defaultWeekStartDay

Allowed types
integer (opens new window)
Default value
1 (Monday)
Defined by
GeneralConfig::$defaultWeekStartDay (opens new window)

The default day 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
->defaultWeekStartDay(0)

# devMode

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$devMode (opens new window)

Whether the system should run in Dev Mode (opens new window).

->devMode(true)

# disabledPlugins

Allowed types
string (opens new window)[], string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$disabledPlugins (opens new window)
Since
3.1.9

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

->disabledPlugins([
    'webhooks',
])

This can also be set to '*' to disable all plugins.

->disabledPlugins('*')

This should not be set on a per-environment basis, as it could result in plugin schema version mismatches between environments, which will prevent project config changes from getting applied.

->disabledPlugins([
    'redactor',
    'webhooks',
])

# disabledUtilities

Allowed types
string (opens new window)[]
Default value
[]
Defined by
GeneralConfig::$disabledUtilities (opens new window)
Since
4.6.0

Array of utility IDs that should be disabled.

 ->disabledUtilities([
     'updates',
     'find-replace',
 ])

# disallowRobots

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$disallowRobots (opens new window)
Since
3.5.10

Whether front end requests should respond with X-Robots-Tag: none HTTP headers, indicating that pages should not be indexed, and links on the page should not be followed, by web crawlers.

This should be set to true for development and staging environments.

->disallowRobots(true)

# enableTemplateCaching

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$enableTemplateCaching (opens new window)

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

->enableTemplateCaching(false)

# errorTemplatePrefix

Allowed types
string (opens new window)
Default value
''
Defined by
GeneralConfig::$errorTemplatePrefix (opens new window)

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 '_' your site’s 404 template would live at templates/_404.twig, for example.

->errorTemplatePrefix('_')

# extraAllowedFileExtensions

Allowed types
string (opens new window)[], null (opens new window)
Default value
null
Defined by
GeneralConfig::$extraAllowedFileExtensions (opens new window)

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

->extraAllowedFileExtensions(['mbox', 'xml'])

# extraAppLocales

Allowed types
string (opens new window)[], null (opens new window)
Default value
null
Defined by
GeneralConfig::$extraAppLocales (opens new window)
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.

->extraAppLocales(['uk'])

# handleCasing

Allowed types
string (opens new window)
Default value
GeneralConfig::CAMEL_CASE
Defined by
GeneralConfig::$handleCasing (opens new window)
Since
3.6.0

The casing to use for autogenerated component handles.

# headlessMode

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$headlessMode (opens new window)
Since
3.3.0

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.

With Headless Mode enabled, users may only set passwords and verify email addresses via the control panel. Be sure to grant “Access the control panel” permission to all content editors and administrators. You’ll also need to set the baseCpUrl config setting if the control panel is located on a different domain than your front end.

->headlessMode(true)

# httpProxy

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$httpProxy (opens new window)
Since
3.7.0

The proxy server that should be used for outgoing HTTP requests.

This can be set to a URL (http://localhost) or a URL plus a port (http://localhost:8125).

->httpProxy('<http://localhost')>

# indexTemplateFilenames

Allowed types
string (opens new window)[]
Default value
[ 'index', ]
Defined by
GeneralConfig::$indexTemplateFilenames (opens new window)

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.

->indexTemplateFilenames(['index', 'default'])

# ipHeaders

Allowed types
string (opens new window)[], null (opens new window)
Default value
null
Defined by
GeneralConfig::$ipHeaders (opens new window)

List of headers where proxies store the real client IP.

See yii\web\Request::$ipHeaders (opens new window) for more details.

If not set, the default craft\web\Request::$ipHeaders (opens new window) value will be used.

->ipHeaders(['X-Forwarded-For', 'CF-Connecting-IP'])

# isSystemLive

Allowed types
boolean (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$isSystemLive (opens new window)

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

->isSystemLive(true)

# limitAutoSlugsToAscii

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$limitAutoSlugsToAscii (opens new window)

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

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

->limitAutoSlugsToAscii(true)

# localeAliases

Allowed types
array (opens new window)
Default value
[]
Defined by
GeneralConfig::$localeAliases (opens new window)
Since
5.0.0

Custom locale aliases, which will be included when fetching all known locales.

Each locale alias should be defined as an array with the following keys:

  • id: The alias locale ID
  • aliasOf: The original locale ID
  • displayName: The locale alias’s display name (optional)

# maxBackups

Allowed types
integer (opens new window), false (opens new window)
Default value
20
Defined by
GeneralConfig::$maxBackups (opens new window)

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

->maxBackups(5)

# maxRevisions

Allowed types
integer (opens new window), null (opens new window)
Default value
50
Defined by
GeneralConfig::$maxRevisions (opens new window)
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.

->maxRevisions(25)

# maxSlugIncrement

Allowed types
integer (opens new window)
Default value
100
Defined by
GeneralConfig::$maxSlugIncrement (opens new window)

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

->maxSlugIncrement(10)

# partialTemplatesPath

Allowed types
string (opens new window)
Default value
'_partials'
Defined by
GeneralConfig::$partialTemplatesPath (opens new window)
Since
5.0.0

The path within the templates folder where element partial templates will live.

Partial templates are used to render elements when calling craft\elements\db\ElementQuery::render() (opens new window), craft\elements\ElementCollection::render() (opens new window), or craft\base\Element::render() (opens new window).

For example, you could render all the entries within a Matrix field like so:

{{ entry.myMatrixField.render() }}

The full path to a partial template will also include the element type handle (e.g. asset or entry) and the field layout provider’s handle (e.g. the volume handle or entry type handle). For an entry of type article, that would be: _partials/entry/article.twig.

->partialTemplatesPath('_cp/partials')

# permissionsPolicyHeader

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$permissionsPolicyHeader (opens new window)
Since
3.6.14

The Permissions-Policy header that should be sent for web responses.

->permissionsPolicyHeader('Permissions-Policy: geolocation=(self)')

# phpMaxMemoryLimit

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$phpMaxMemoryLimit (opens new window)

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 can.

See https://php.net/manual/en/faq.using.php#faq.using.shorthandbytes (opens new window) for a list of acceptable values.

->phpMaxMemoryLimit('512M')

# preloadSingles

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$preloadSingles (opens new window)
Since
4.4.0

Whether Single section entries should be preloaded for Twig templates.

When enabled, Craft will make an educated guess on which Singles should be preloaded for each template based on the variable names that are referenced.

You will need to clear your compiled templates from the Caches utility before this setting will take effect.

->preloadSingles()

# previewIframeResizerOptions

Allowed types
array (opens new window)
Default value
[]
Defined by
GeneralConfig::$previewIframeResizerOptions (opens new window)
Since
3.5.0

Custom iFrame Resizer options (opens new window) that should be used for preview iframes.

->previewIframeResizerOptions([
    'autoResize' => false,
])

# privateTemplateTrigger

Allowed types
string (opens new window)
Default value
'_'
Defined by
GeneralConfig::$privateTemplateTrigger (opens new window)

The template path segment prefix that should be used to identify “private” templates, which are templates that are not directly accessible via a matching URL.

Set to an empty value to disable public template routing.

->privateTemplateTrigger('')

# runQueueAutomatically

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$runQueueAutomatically (opens new window)

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 (opens new window), or a cron job that runs the queue/run command every minute:

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

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

->runQueueAutomatically(false)

# sameSiteCookieValue

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$sameSiteCookieValue (opens new window)
Since
3.1.33

The SameSite (opens new window) value that should be set on Craft cookies, if any.

# sendContentLengthHeader

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$sendContentLengthHeader (opens new window)
Since
3.7.3

Whether a Content-Length header should be sent with responses.

->sendContentLengthHeader(true)

# sendPoweredByHeader

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$sendPoweredByHeader (opens new window)

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

->sendPoweredByHeader(false)

# slugWordSeparator

Allowed types
string (opens new window)
Default value
'-'
Defined by
GeneralConfig::$slugWordSeparator (opens new window)

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

->slugWordSeparator('.')

# testToEmailAddress

Allowed types
string (opens new window), array (opens new window), null (opens new window), false (opens new window)
Default value
null
Defined by
GeneralConfig::$testToEmailAddress (opens new window)

Configures Craft to send all system emails to either 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 ['me@domain.tld' => 'Name'].

->testToEmailAddress('me@domain.tld')

# timezone

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$timezone (opens new window)

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 (opens new window).

->timezone('Europe/London')

# translationDebugOutput

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$translationDebugOutput (opens new window)

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.

->translationDebugOutput(true)

# useEmailAsUsername

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$useEmailAsUsername (opens new window)

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

If you enable this setting after user accounts already exist, run this terminal command to update existing usernames:

php craft utils/update-usernames

->useEmailAsUsername(true)

# useFileLocks

Allowed types
boolean (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$useFileLocks (opens new window)

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 null, Craft will try to detect if the underlying file system supports exclusive file locking and cache the results.

->useFileLocks(false)

# useIframeResizer

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$useIframeResizer (opens new window)
Since
3.5.5

Whether iFrame Resizer options (opens new window) should be used for Live Preview.

Using iFrame Resizer makes it possible for Craft to retain the preview’s scroll position between page loads, for cross-origin web pages.

It works by setting the height of the iframe to match the height of the inner web page, and the iframe’s container will be scrolled rather than the iframe document itself. This can lead to some unexpected CSS issues, however, because the previewed viewport height will be taller than the visible portion of the iframe.

If you have a decoupled front end (opens new window), you will need to include iframeResizer.contentWindow.min.js (opens new window) on your page as well for this to work. You can conditionally include it for only Live Preview requests by checking if the requested URL contains a x-craft-live-preview query string parameter.

You can customize the behavior of iFrame Resizer via the previewIframeResizerOptions config setting.

->useIframeResizer(true)

# Environment

# aliases

Allowed types
array (opens new window)
Default value
[]
Defined by
GeneralConfig::$aliases (opens new window)

Any custom Yii aliases (opens new window) that should be defined for every request.

->aliases([
    '@webroot' => '/var/www/',
])

# backupCommand

Allowed types
string (opens new window), null (opens new window), false (opens new window)
Default value
null
Defined by
GeneralConfig::$backupCommand (opens new window)

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

When set to null (default), Craft will run mysqldump or pg_dump, provided that those libraries are in the $PATH variable for the system user running the web server.

You may provide your own command, which can include several tokens Craft will substitute at runtime:

  • {file} - the target backup file path
  • {port} - the current database port
  • {server} - the current database hostname
  • {user} - user that was used to connect to the database
  • {password} - password for the specified {user}
  • {database} - the current database name
  • {schema} - the current database schema (if any)

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

->backupCommand(false)

# buildId

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$buildId (opens new window)
Since
4.0.0

A unique ID representing the current build of the codebase.

This should be set to something unique to the deployment, e.g. a Git SHA or a deployment timestamp.

->buildId(\craft\helpers\App::env('GIT_SHA'))

# defaultCookieDomain

Allowed types
string (opens new window)
Default value
''
Defined by
GeneralConfig::$defaultCookieDomain (opens new window)

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 '.my-project.tld'.

->defaultCookieDomain('.my-project.tld')

# resourceBasePath

Allowed types
string (opens new window)
Default value
'@webroot/cpresources'
Defined by
GeneralConfig::$resourceBasePath (opens new window)

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

->resourceBasePath('@webroot/craft-resources')

# resourceBaseUrl

Allowed types
string (opens new window)
Default value
'@web/cpresources'
Defined by
GeneralConfig::$resourceBaseUrl (opens new window)

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

->resourceBaseUrl('@web/craft-resources')

# restoreCommand

Allowed types
string (opens new window), null (opens new window), false (opens new window)
Default value
null
Defined by
GeneralConfig::$restoreCommand (opens new window)

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

By default Craft will run mysql or psql, provided 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 hostname
  • {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.

->restoreCommand(false)

# Routing

# actionTrigger

Allowed types
string (opens new window)
Default value
'actions'
Defined by
GeneralConfig::$actionTrigger (opens new window)

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

->actionTrigger('do-it')

# activateAccountSuccessPath

Allowed types
mixed
Default value
''
Defined by
GeneralConfig::$activateAccountSuccessPath (opens new window)

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

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

->activateAccountSuccessPath('welcome')

# addTrailingSlashesToUrls

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$addTrailingSlashesToUrls (opens new window)

Whether auto-generated URLs should have trailing slashes.

->addTrailingSlashesToUrls(true)

# allowUppercaseInSlug

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$allowUppercaseInSlug (opens new window)

Whether uppercase letters should be allowed in slugs.

->allowUppercaseInSlug(true)

# baseCpUrl

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$baseCpUrl (opens new window)

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

It will be determined automatically if left blank.

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

->baseCpUrl('<https://cms.my-project.tld/')>

# cpTrigger

Allowed types
string (opens new window), null (opens new window)
Default value
'admin'
Defined by
GeneralConfig::$cpTrigger (opens new window)

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.

This can be set to null if you have a dedicated hostname for the control panel (e.g. cms.my-project.tld), or you are running Craft in Headless Mode. If you do that, you will need to ensure that the control panel is being served from its own web root directory on your server, with an index.php file that defines the CRAFT_CP PHP constant.

define('CRAFT_CP', true);

Alternatively, you can set the baseCpUrl config setting, but then you will run the risk of losing access to portions of your control panel due to URI conflicts with actual folders/files in your main web root.

(For example, if you have an assets/ folder, that would conflict with the /assets page in the control panel.)

->cpTrigger(null)

# invalidUserTokenPath

Allowed types
mixed
Default value
''
Defined by
GeneralConfig::$invalidUserTokenPath (opens new window)

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() (opens new window) for a list of supported value types.

// 1 day
->invalidUserTokenPath('nope')

# loginPath

Allowed types
mixed
Default value
'login'
Defined by
GeneralConfig::$loginPath (opens new window)

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

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

Note that this config setting is ignored when headlessMode is enabled.

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

->loginPath(false)

# logoutPath

Allowed types
mixed
Default value
'logout'
Defined by
GeneralConfig::$logoutPath (opens new window)

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

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

Note that this config setting is ignored when headlessMode is enabled.

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

->logoutPath(false)

# omitScriptNameInUrls

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$omitScriptNameInUrls (opens new window)

Whether generated URLs should omit index.php (e.g. http://my-project.tld/path instead of http://my-project.tld/index.php/path)

This can only be possible if your server is configured to redirect would-be 404s 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= [QSA,L]

->omitScriptNameInUrls(true)

Even when this is set to true, the script name could still be included in some action URLs. If you want to ensure that index.php is fully omitted from all generated URLs, set the pathParam config setting to null.

# pageTrigger

Allowed types
string (opens new window)
Default value
'p'
Defined by
GeneralConfig::$pageTrigger (opens new window)

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

If you want to set this to ?p (e.g. /news?p=5), you’ll also need to change your pathParam setting which defaults to p. If your server is running Apache, you’ll need to update the redirect code in your .htaccess file to match your new pathParam value.

->pageTrigger('page')

# pathParam

Allowed types
string (opens new window), null (opens new window)
Default value
'p'
Defined by
GeneralConfig::$pathParam (opens new window)

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

This can be set to null if your web server is capable of directing traffic to index.php without a query string param. If you’re using Apache, that means you’ll need to change the RewriteRule line in your .htaccess file to:

RewriteRule (.+) index.php [QSA,L]

->pathParam(null)

# postCpLoginRedirect

Allowed types
mixed
Default value
'dashboard'
Defined by
GeneralConfig::$postCpLoginRedirect (opens new window)

The path users should be redirected to after logging into 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() (opens new window) for a list of supported value types.

->postCpLoginRedirect('entries')

# postLoginRedirect

Allowed types
mixed
Default value
''
Defined by
GeneralConfig::$postLoginRedirect (opens new window)

The path 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() (opens new window) for a list of supported value types.

->postLoginRedirect('welcome')

# postLogoutRedirect

Allowed types
mixed
Default value
''
Defined by
GeneralConfig::$postLogoutRedirect (opens new window)

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

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

->postLogoutRedirect('goodbye')

# setPasswordPath

Allowed types
mixed
Default value
'setpassword'
Defined by
GeneralConfig::$setPasswordPath (opens new window)

The URI or URL that Craft should use for Set Password forms on the front end.

This setting is ignored when headlessMode is enabled, unless it’s set to an absolute URL.

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

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

->setPasswordPath('set-password')

# setPasswordRequestPath

Allowed types
mixed
Default value
null
Defined by
GeneralConfig::$setPasswordRequestPath (opens new window)
Since
3.5.14

The URI to the page where users can request to change their password.

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

If this is set, Craft will redirect .well-known/change-password requests (opens new window) to this URI.

You’ll also need to set setPasswordPath, which determines the URI and template path for the Set Password form where the user resets their password after following the link in the Password Reset email.

->setPasswordRequestPath('request-password')

# setPasswordSuccessPath

Allowed types
mixed
Default value
''
Defined by
GeneralConfig::$setPasswordSuccessPath (opens new window)

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

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

->setPasswordSuccessPath('password-set')

# siteToken

Allowed types
string (opens new window)
Default value
'siteToken'
Defined by
GeneralConfig::$siteToken (opens new window)
Since
3.5.0

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

->siteToken('t')

# tokenParam

Allowed types
string (opens new window)
Default value
'token'
Defined by
GeneralConfig::$tokenParam (opens new window)

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

->tokenParam('t')

# usePathInfo

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$usePathInfo (opens new window)

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

This setting only takes effect if omitScriptNameInUrls is set to false.

->usePathInfo(true)

# useSslOnTokenizedUrls

Allowed types
boolean (opens new window), string (opens new window)
Default value
'auto'
Defined by
GeneralConfig::$useSslOnTokenizedUrls (opens new window)

Determines what protocol/schema Craft will use when generating tokenized URLs. If set to 'auto', Craft will check the current site’s base URL 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, Craft will always use http. If set to true, then, Craft will always use https.

->useSslOnTokenizedUrls(true)

# verifyEmailPath

Allowed types
mixed
Default value
'verifyemail'
Defined by
GeneralConfig::$verifyEmailPath (opens new window)
Since
3.4.0

The URI or URL that Craft should use for email verification links on the front end.

This setting is ignored when headlessMode is enabled, unless it’s set to an absolute URL.

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

->verifyEmailPath('verify-email')

# verifyEmailSuccessPath

Allowed types
mixed
Default value
''
Defined by
GeneralConfig::$verifyEmailSuccessPath (opens new window)
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() (opens new window) for a list of supported value types.

->verifyEmailSuccessPath('verified-email')

# Session

# phpSessionName

Allowed types
string (opens new window)
Default value
'CraftSessionId'
Defined by
GeneralConfig::$phpSessionName (opens new window)

The name of the PHP session cookie.

->phpSessionName(null)

# rememberUsernameDuration

Allowed types
mixed
Default value
31536000 (1 year)
Defined by
GeneralConfig::$rememberUsernameDuration (opens new window)

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() (opens new window) for a list of supported value types.

->rememberUsernameDuration(0)

# rememberedUserSessionDuration

Allowed types
mixed
Default value
1209600 (14 days)
Defined by
GeneralConfig::$rememberedUserSessionDuration (opens new window)

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() (opens new window) for a list of supported value types.

->rememberedUserSessionDuration(0)

# requireMatchingUserAgentForSession

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$requireMatchingUserAgentForSession (opens new window)

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

->requireMatchingUserAgentForSession(false)

# requireUserAgentAndIpForSession

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$requireUserAgentAndIpForSession (opens new window)

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

->requireUserAgentAndIpForSession(false)

# userSessionDuration

Allowed types
mixed
Default value
3600 (1 hour)
Defined by
GeneralConfig::$userSessionDuration (opens new window)

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() (opens new window) for a list of supported value types.

// 3 hours
->userSessionDuration(10800)

# Security

# blowfishHashCost

Allowed types
integer (opens new window)
Default value
13
Defined by
GeneralConfig::$blowfishHashCost (opens new window)

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.

->blowfishHashCost(15)

# cooldownDuration

Allowed types
mixed
Default value
300 (5 minutes)
Defined by
GeneralConfig::$cooldownDuration (opens new window)

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() (opens new window) for a list of supported value types.

->cooldownDuration(0)

# csrfTokenName

Allowed types
string (opens new window)
Default value
'CRAFT_CSRF_TOKEN'
Defined by
GeneralConfig::$csrfTokenName (opens new window)

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

->csrfTokenName('MY_CSRF')

# defaultTokenDuration

Allowed types
mixed
Default value
86400 (1 day)
Defined by
GeneralConfig::$defaultTokenDuration (opens new window)

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

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

// One week
->defaultTokenDuration(604800)

# deferPublicRegistrationPassword

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$deferPublicRegistrationPassword (opens new window)

By default, Craft requires a front-end “password” field for public user registrations. Setting this to true removes that requirement for the initial registration form.

If you have email verification enabled, new users will set their password once they’ve followed 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.

->deferPublicRegistrationPassword(true)

# elevatedSessionDuration

Allowed types
mixed
Default value
300 (5 minutes)
Defined by
GeneralConfig::$elevatedSessionDuration (opens new window)

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() (opens new window) for a list of supported value types.

->elevatedSessionDuration(0)

# enableBasicHttpAuth

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$enableBasicHttpAuth (opens new window)
Since
3.5.0

Whether front-end web requests should support basic HTTP authentication.

->enableBasicHttpAuth(true)

# enableCsrfCookie

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$enableCsrfCookie (opens new window)

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.

->enableCsrfCookie(false)

# enableCsrfProtection

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$enableCsrfProtection (opens new window)

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

->enableCsrfProtection(false)

# invalidLoginWindowDuration

Allowed types
mixed
Default value
3600 (1 hour)
Defined by
GeneralConfig::$invalidLoginWindowDuration (opens new window)

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() (opens new window) for a list of supported value types.

// 1 day
->invalidLoginWindowDuration(86400)

# maxInvalidLogins

Allowed types
integer (opens new window), false (opens new window)
Default value
5
Defined by
GeneralConfig::$maxInvalidLogins (opens new window)

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

->maxInvalidLogins(3)

# preventUserEnumeration

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$preventUserEnumeration (opens new window)

When true, Craft will always return a successful response in the “forgot password” flow, making it difficult to enumerate users.

When set to false and you go through the “forgot password” flow from the control panel login page, you’ll get distinct messages indicating whether the username/email exists and whether an email was sent with further instructions. This can be helpful for the user attempting to log in but allow for username/email enumeration based on the response.

->preventUserEnumeration(true)

# previewTokenDuration

Allowed types
mixed
Default value
null (1 day)
Defined by
GeneralConfig::$previewTokenDuration (opens new window)
Since
3.7.0

The amount of time content preview tokens can be used before expiring.

Defaults to defaultTokenDuration value.

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

// 1 hour
->previewTokenDuration(3600)

# sanitizeCpImageUploads

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$sanitizeCpImageUploads (opens new window)
Since
3.6.0

Whether images uploaded via the control panel should be sanitized.

->sanitizeCpImageUploads(false)

# sanitizeSvgUploads

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$sanitizeSvgUploads (opens new window)

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.

->sanitizeSvgUploads(false)

# secureHeaders

Allowed types
array (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$secureHeaders (opens new window)

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

See yii\web\Request::$secureHeaders (opens new window) for more details.

If not set, the default yii\web\Request::$secureHeaders (opens new window) value will be used.

->secureHeaders([
    'X-Forwarded-For',
    'X-Forwarded-Host',
    'X-Forwarded-Proto',
    'X-Rewrite-Url',
    'X-Original-Host',
    'CF-Connecting-IP',
])

# secureProtocolHeaders

Allowed types
array (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$secureProtocolHeaders (opens new window)

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

See yii\web\Request::$secureProtocolHeaders (opens new window) for more details.

If not set, the default yii\web\Request::$secureProtocolHeaders (opens new window) value will be used.

->secureProtocolHeaders([
    'X-Forwarded-Proto' => [
        'https',
    ],
    'Front-End-Https' => [
        'on',
    ],
    'CF-Visitor' => [
        '{\"scheme\":\"https\"}',
    ],
])

# securityKey

Allowed types
string (opens new window)
Default value
''
Defined by
GeneralConfig::$securityKey (opens new window)

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

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

->securityKey('2cf24dba5...')

# storeUserIps

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$storeUserIps (opens new window)
Since
3.1.0

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

->storeUserIps(true)

# trustedHosts

Allowed types
array (opens new window)
Default value
[ 'any', ]
Defined by
GeneralConfig::$trustedHosts (opens new window)

The configuration for trusted security-related headers.

See yii\web\Request::$trustedHosts (opens new window) for more details.

By default, all hosts are trusted.

->trustedHosts(['trusted-one.foo', 'trusted-two.foo'])

# useSecureCookies

Allowed types
boolean (opens new window), string (opens new window)
Default value
'auto'
Defined by
GeneralConfig::$useSecureCookies (opens new window)

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.

->useSecureCookies(true)

# verificationCodeDuration

Allowed types
mixed
Default value
86400 (1 day)
Defined by
GeneralConfig::$verificationCodeDuration (opens new window)

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

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

// 1 hour
->verificationCodeDuration(3600)

# Assets

# allowedFileExtensions

Allowed types
string (opens new window)[]
Default value
[ '7z', 'aiff', 'asc', 'asf', 'avi', 'avif', 'bmp', 'cap', 'cin', 'csv', 'dfxp', 'doc', 'docx', 'dotm', 'dotx', 'fla', 'flv', 'gif', 'gz', 'gzip', 'heic', 'heif', 'hevc', 'itt', 'jp2', 'jpeg', 'jpg', 'jpx', 'js', 'json', 'lrc', 'm2t', 'm4a', 'm4v', 'mcc', 'mid', 'mov', 'mp3', 'mp4', 'mpc', 'mpeg', 'mpg', 'mpsub', 'ods', 'odt', 'ogg', 'ogv', 'pdf', 'png', 'potx', 'pps', 'ppsm', 'ppsx', 'ppt', 'pptm', 'pptx', 'ppz', 'pxd', 'qt', 'ram', 'rar', 'rm', 'rmi', 'rmvb', 'rt', 'rtf', 'sami', 'sbv', 'scc', 'sdc', 'sitd', 'smi', 'srt', 'stl', 'sub', 'svg', 'swf', 'sxc', 'sxw', 'tar', 'tds', 'tgz', 'tif', 'tiff', 'ttml', 'txt', 'vob', 'vsd', 'vtt', 'wav', 'webm', 'webp', 'wma', 'wmv', 'xls', 'xlsx', 'zip', ]
Defined by
GeneralConfig::$allowedFileExtensions (opens new window)

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

// Nothing bug GIFs!
->allowedFileExtensions([
    'gif',
])

# convertFilenamesToAscii

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$convertFilenamesToAscii (opens new window)

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

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

->convertFilenamesToAscii(false)

# extraFileKinds

Allowed types
array (opens new window)
Default value
[]
Defined by
GeneralConfig::$extraFileKinds (opens new window)
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'],
    ],
])

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

# filenameWordSeparator

Allowed types
string (opens new window), false (opens new window)
Default value
'-'
Defined by
GeneralConfig::$filenameWordSeparator (opens new window)

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

->filenameWordSeparator(false)

# maxUploadFileSize

Allowed types
integer (opens new window), string (opens new window)
Default value
16777216 (16MB)
Defined by
GeneralConfig::$maxUploadFileSize (opens new window)

The maximum upload file size allowed.

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

// 25MB
->maxUploadFileSize(26214400)

# revAssetUrls

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$revAssetUrls (opens new window)
Since
3.7.0

Whether asset URLs should be revved so browsers don’t load cached versions when they’re modified.

->revAssetUrls(true)

# tempAssetUploadFs

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$tempAssetUploadFs (opens new window)
Since
5.0.0

The handle of the filesystem that should be used for storing temporary asset uploads. A local temp folder will be used by default.

->tempAssetUploadFs('$TEMP_ASSET_UPLOADS_FS')

# Image Handling

# brokenImagePath

Allowed types
string (opens new window), null (opens new window)
Default value
null
Defined by
GeneralConfig::$brokenImagePath (opens new window)
Since
3.5.0

The server path to an image file that should be sent when responding to an image request with a 404 status code.

This can be set to an aliased path such as @webroot/assets/404.svg.

->brokenImagePath('@webroot/assets/404.svg')

# defaultImageQuality

Allowed types
integer (opens new window)
Default value
82
Defined by
GeneralConfig::$defaultImageQuality (opens new window)

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

->defaultImageQuality(90)

# generateTransformsBeforePageLoad

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$generateTransformsBeforePageLoad (opens new window)

Whether image transforms should be generated before page load.

->generateTransformsBeforePageLoad(true)

# imageDriver

Allowed types
mixed
Default value
GeneralConfig::IMAGE_DRIVER_AUTO
Defined by
GeneralConfig::$imageDriver (opens new window)

The image driver Craft should use to cleanse and transform images. By default Craft will use ImageMagick if it’s installed and otherwise fall back to GD. You can explicitly set either 'imagick' or 'gd' here to override that behavior.

->imageDriver('imagick')

# imageEditorRatios

Allowed types
array (opens new window)
Default value
[ 'Unconstrained' => 'none', 'Original' => 'original', 'Square' => 1, '16:9' => 1.78, '10:8' => 1.25, '7:5' => 1.4, '4:3' => 1.33, '5:3' => 1.67, '3:2' => 1.5, ]
Defined by
GeneralConfig::$imageEditorRatios (opens new window)

An array containing the selectable image aspect ratios for the image editor. The array must be in the format of label => ratio, where ratio must be a float or a string. For string values, only values of “none” and “original” are allowed.

->imageEditorRatios([
    'Unconstrained' => 'none',
    'Original' => 'original',
    'Square' => 1,
    'IMAX' => 1.9,
    'Widescreen' => 1.78,
])

# maxCachedCloudImageSize

Allowed types
integer (opens new window)
Default value
2000
Defined by
GeneralConfig::$maxCachedCloudImageSize (opens new window)

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

->maxCachedCloudImageSize(0)

# optimizeImageFilesize

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$optimizeImageFilesize (opens new window)

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

->optimizeImageFilesize(false)

# preserveCmykColorspace

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$preserveCmykColorspace (opens new window)
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 image color distortion. This will only have an effect if ImageMagick is in use.

->preserveCmykColorspace(true)

# preserveExifData

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$preserveExifData (opens new window)

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.

->preserveExifData(true)

# preserveImageColorProfiles

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$preserveImageColorProfiles (opens new window)

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.

->preserveImageColorProfiles(false)

# rasterizeSvgThumbs

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$rasterizeSvgThumbs (opens new window)
Since
3.6.0

Whether SVG thumbnails should be rasterized.

This will only work if ImageMagick is installed, and imageDriver is set to either auto or imagick.

->rasterizeSvgThumbs(true)

# rotateImagesOnUploadByExifData

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$rotateImagesOnUploadByExifData (opens new window)

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

->rotateImagesOnUploadByExifData(false)

# transformGifs

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$transformGifs (opens new window)
Since
3.0.7

Whether GIF files should be cleansed/transformed.

->transformGifs(false)

# transformSvgs

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$transformSvgs (opens new window)
Since
3.7.1

Whether SVG files should be transformed.

->transformSvgs(false)

# upscaleImages

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$upscaleImages (opens new window)
Since
3.4.0

Whether image transforms should allow upscaling by default, for images that are smaller than the transform dimensions.

->upscaleImages(false)

# GraphQL

# allowedGraphqlOrigins

Allowed types
string (opens new window)[], null (opens new window), false (opens new window)
Default value
null
Defined by
GeneralConfig::$allowedGraphqlOrigins (opens new window)
Since
3.5.0

The Ajax origins that should be allowed to access the GraphQL API, if enabled.

If this is set to an array, then graphql/api requests will only include the current request’s origin (opens new window) in the Access-Control-Allow-Origin response header if it’s listed here.

If this is set to false, then the Access-Control-Allow-Origin response header will never be sent.

->allowedGraphqlOrigins(false)

# disableGraphqlTransformDirective

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$disableGraphqlTransformDirective (opens new window)
Since
3.6.0

Whether the transform directive should be disabled for the GraphQL API.

->disableGraphqlTransformDirective(true)

# enableGql

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$enableGql (opens new window)
Since
3.3.1

Whether the GraphQL API should be enabled.

The GraphQL API is only available for Craft Pro.

->enableGql(false)

# enableGraphqlCaching

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$enableGraphqlCaching (opens new window)
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 (opens new window) event to provide its own caching logic and setting the result property.

->enableGraphqlCaching(false)

# enableGraphqlIntrospection

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$enableGraphqlIntrospection (opens new window)
Since
3.6.0

Whether GraphQL introspection queries are allowed. Defaults to true and is always allowed in the control panel.

->enableGraphqlIntrospection(false)

# gqlTypePrefix

Allowed types
string (opens new window)
Default value
''
Defined by
GeneralConfig::$gqlTypePrefix (opens new window)

Prefix to use for all type names returned by GraphQL.

->gqlTypePrefix('craft_')

# maxGraphqlBatchSize

Allowed types
integer (opens new window)
Default value
0
Defined by
GeneralConfig::$maxGraphqlBatchSize (opens new window)
Since
4.5.5

The maximum allowed GraphQL queries that can be executed in a single batched request. Set to 0 to allow any number of queries.

->maxGraphqlBatchSize(5)

# maxGraphqlComplexity

Allowed types
integer (opens new window)
Default value
0
Defined by
GeneralConfig::$maxGraphqlComplexity (opens new window)
Since
3.6.0

The maximum allowed complexity a GraphQL query is allowed to have. Set to 0 to allow any complexity.

->maxGraphqlComplexity(500)

# maxGraphqlDepth

Allowed types
integer (opens new window)
Default value
0
Defined by
GeneralConfig::$maxGraphqlDepth (opens new window)
Since
3.6.0

The maximum allowed depth a GraphQL query is allowed to reach. Set to 0 to allow any depth.

->maxGraphqlDepth(5)

# maxGraphqlResults

Allowed types
integer (opens new window)
Default value
0
Defined by
GeneralConfig::$maxGraphqlResults (opens new window)
Since
3.6.0

The maximum allowed results for a single GraphQL query. Set to 0 to disable any limits.

->maxGraphqlResults(100)

# prefixGqlRootTypes

Allowed types
boolean (opens new window)
Default value
true
Defined by
GeneralConfig::$prefixGqlRootTypes (opens new window)
Since
3.6.6

Whether the gqlTypePrefix config setting should have an impact on query, mutation, and subscription types.

->prefixGqlRootTypes(false)

# setGraphqlDatesToSystemTimeZone

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$setGraphqlDatesToSystemTimeZone (opens new window)
Since
3.7.0

Whether dates returned by the GraphQL API should be set to the system time zone by default, rather than UTC.

->setGraphqlDatesToSystemTimeZone(true)

# Garbage Collection

# purgePendingUsersDuration

Allowed types
mixed
Default value
0
Defined by
GeneralConfig::$purgePendingUsersDuration (opens new window)

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

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() (opens new window) for a list of supported value types.

Users will only be purged when garbage collection (opens new window) is run.

// 2 weeks
->purgePendingUsersDuration(1209600)

# purgeStaleUserSessionDuration

Allowed types
mixed
Default value
7776000 (90 days)
Defined by
GeneralConfig::$purgeStaleUserSessionDuration (opens new window)
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() (opens new window) for a list of supported value types.

// 1 week
->purgeStaleUserSessionDuration(604800)

# purgeUnsavedDraftsDuration

Allowed types
mixed
Default value
2592000 (30 days)
Defined by
GeneralConfig::$purgeUnsavedDraftsDuration (opens new window)
Since
3.2.0

The amount of time to wait before Craft purges unpublished drafts that were never updated with content.

Set to 0 to disable this feature.

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

->purgeUnsavedDraftsDuration(0)

# softDeleteDuration

Allowed types
mixed
Default value
2592000 (30 days)
Defined by
GeneralConfig::$softDeleteDuration (opens new window)
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() (opens new window) for a list of supported value types.

->softDeleteDuration(0)

# Users

# extraLastNamePrefixes

Allowed types
string (opens new window)[]
Default value
[]
Defined by
GeneralConfig::$extraLastNamePrefixes (opens new window)
Since
4.3.0

Any additional last name prefixes that should be supported by the name parser.

->extraLastNamePrefixes(['Dal', 'Van Der'])

# extraNameSalutations

Allowed types
string (opens new window)[]
Default value
[]
Defined by
GeneralConfig::$extraNameSalutations (opens new window)
Since
4.3.0

Any additional name salutations that should be supported by the name parser.

->extraNameSalutations(['Lady', 'Sire'])

# extraNameSuffixes

Allowed types
string (opens new window)[]
Default value
[]
Defined by
GeneralConfig::$extraNameSuffixes (opens new window)
Since
4.3.0

Any additional name suffixes that should be supported by the name parser.

->extraNameSuffixes(['CCNA', 'OBE'])

# showFirstAndLastNameFields

Allowed types
boolean (opens new window)
Default value
false
Defined by
GeneralConfig::$showFirstAndLastNameFields (opens new window)
Since
4.6.0

Whether “First Name” and “Last Name” fields should be shown in place of “Full Name” fields.

->showFirstAndLastNameFields()
Parts of this page are generated or assembled by automations. While we greatly appreciate contributions to the documentation, reporting automated content issues will allow us to fix them at the source!