Configuration Overview

There are several ways to configure Craft depending on your needs.

General Config Settings

Craft supports several general config settings. You can override their default values in your config/general.php file.

return [
    'devMode' => true,
];

Database Connection Settings

Craft supports several database connection settings. You can override their default values in your config/db.php file.

Guzzle Config

Craft uses Guzzle 6 whenever creating HTTP requests, such as:

  • when checking for Craft updates
  • when sending in a support request from the Craft Support widget
  • when loading RSS feeds from the Feeds widget
  • when working with assets on remote volumes, like Amazon S3

You can customize the config settings Guzzle uses when sending these requests by creating a guzzle.php file in your config/ folder. The file should return an array, with your config overrides.

<?php

return [
    'headers' => ['Foo' => 'Bar'],
    'query'   => ['testing' => '123'],
    'auth'    => ['username', 'password'],
    'proxy'   => 'tcp://localhost:80',
];

The options defined here will be passed into new GuzzleHttp\Client instances. See Guzzle’s documentation for a list of available options.

Aliases

Some settings and functions in Craft support Yii aliases, which are basically placeholders for base file system paths and URLs. These include:

The following aliases are available out of the box:

AliasDescription
@appThe path to vendor/craftcms/cms/src/
@configThe path to your config/ folder
@contentMigrationsThe path to your migrations/ folder
@craftThe path to vendor/craftcms/cms/src/
@libThe path to vendor/craftcms/cms/lib/
@rootThe root project path (same as the CRAFT_BASE_PATH PHP constant)
@runtimeThe path to your storage/runtime/ folder
@storageThe path to your storage/ folder
@templatesThe path to your templates/ folder
@translationsThe path to your translations/ folder
@vendorThe path to your vendor/ folder
@webThe URL to the folder that contains the index.php file that was loaded for the request
@webrootThe path to the folder that contains the index.php file that was loaded for the request

You can override these default aliases with the aliases config setting if needed. It’s recommended to override the @web alias if you plan on using it, to avoid a cache poisoning vulnerability.

'aliases' => [
    '@web' => 'http://my-project.com',
];

If your webroot is something besides web/, public/, public_html/, or html/, or it’s not located alongside your craft executable, you will also need to override the @webroot alias, so it can be defined properly for console commands.

'aliases' => [
    '@web' => 'http://my-project.com',
    '@webroot' => dirname(__DIR__) . '/path/to/webroot',
];

You can define additional custom aliases using the aliases config setting as well. For example, you may wish to create aliases that define the base URL and base path that your asset volumes will live in.

'aliases' => [
    '@web' => 'http://my-project.com',
    '@webroot' => dirname(__DIR__) . '/path/to/webroot',
    '@assetBaseUrl' => '@web/assets',
    '@assetBasePath' => '@webroot/assets',
],

With those in place, you could begin your asset volumes’ Base URL and File System Path settings with them, e.g. @assetBaseUrl/user-photos and @assetBasePath/user-photos.

If you’d like, you can set the alias values with environment variables, either from your .env file or somewhere in your environment’s configuration:

ASSETS_BASE_URL=http://my-project.com/assets
ASSETS_BASE_PATH=/path/to/webroot/assets

Then you can pull them into the alias definitions using getenv():

'aliases' => [
    '@assetBaseUrl' => getenv('ASSETS_BASE_URL'),
    '@assetBasePath' => getenv('ASSETS_BASE_PATH'),
],

TIP

When referencing aliases in your settings, you can append additional segments onto the URL or path. For example, you can set a volume’s base URL to @assetBaseUrl/user-photos.

TIP

You can parse aliases in your templates by passing them to the alias() function:

{{ alias('@assetBaseUrl') }}

URL Rules

You can define custom URL rules in config/routes.php. See Routing for more details.

PHP Constants

You can configure core settings like system file paths and the active environment by defining certain PHP constants in web/index.php.

Application Configuration

You can customize Craft’s application configuration from config/app.php, such as overriding component configs, or adding new modules and components.