Configuring your application


The FuelPHP framework is built with configuration over convention in mind. This results in a highly customizable base on which you can start building your application.

Configuration files are stored inside the app/config folder. The application's basic configuration is done in app/config/config.php. The loaded configuration can be made environment specific, more on this under Environments.

To overwrite settings from feature specific configs, either create a new file in app/config or copy the corresponding file from core/config to app/config.

Configuration options

These are the options that can be defined in the applications basic configuration file, app/config/config.php. When you have just installed FuelPHP, this file is empty. All default values, as defined below, are defined in the corresponding file in the core/config folder. When you want to override a default, add the key to the array in your app config file, and modify the value. Alternatively, copy the section from the core file to the app file, and modify it.

FuelPHP uses "dot-notation" when handling arrays. It is a convenient way of accessing elements of a multi-dimensional array. This notation is used in the documenation as well, as it provides an easy to type array reference. For example:

// when you see "always_load.packages = array()", it is shorthand for:
array("always_load" => array("packages" => array(...) ) );
Key Type Default Description
base_url string
The base URL of the application. Can be relative. MUST contain a trailing slash. ('/foo/', '')
url_suffix string
Any suffix that needs to be added to URL's generated by Fuel. If the suffix is an extension, make sure to include the dot. ('.html')
index_file string
The name of the main bootstrap file. Set this to false or remove if you using mod_rewrite.
controller_prefix string
The class prefix used to find controllers when mapping the URI to the controller class name. You have to change this if you want your controllers namespaced or in a different folder then app/classes/controller.
profiling bool
Whether to enable the profiler.
cache_dir string
The directory to store cache files in. This directory must be writable.
caching bool
Whether to enable file finder caching.
cache_lifetime int
The file finder cache lifetime in seconds.
ob_callback callback
Callback given to ob_start(), set to ob_gzhandler to enable gzip encoding of output.
errors array Array, containing the configuration keys to control behaviour when detecting errors:
errors.continue_on array
On which php errors to proceed execution. See Error handling.
errors.throttle int
How many errors to show before we stop showing them. (prevents out-of-memory errors)
errors.notices bool
Whether to show notices.
language string
The default application language, used by the Lang class.
locale string
Used for setlocale() required on some php installations, set to false to prevent it from being set.
The syntax setting for this can differ per OS, Ubuntu for example requires a .utf8 (the encoding) suffix.
encoding string
The application's default character encoding.
server_gmt_offset int
The offset in seconds the server offset from gmt timestamp when time() is used.
This is only to correct bad server configuration: time() should always return the number of seconds since January 1 1970 00:00:00 GMT.
default_timezone string
The server timezone.

If you set this value, make ABSOLUTELY sure that the timezone configured matches the timezone set on your server. Since timezone calculations work by converting to GMT, it goes horribly wrong when you have a timezone mismatch. This will cause time displays in your application to be incorrect, and cookie/session issues due to incorrect expiry time calculations!

log_threshold int
The logging threshold. From what level of message to log, or an array of specific message levels that should be logged. Read about the possible values
log_path string
The directory to store the logs in. This directory MUST be writable.
log_date_format string
'Y-m-d H:i:s'
The date/time format used in the logs.
security array Array, containing the configuration keys to control your application security:
security.csrf_autoload bool
Whether to auto-check the csrf token. Read more about csrf.
security.csrf_token_key string
Which $_POST key to fetch when checking the csrf token.
security.csrf_expiration int
Set the expiration time for the csrf cookie. Anything higher than 0 is the number of seconds in which the cookie will expire.
security.token_salt string
'put your salt value here to make the token more secure'
A salt to make sure the generated security tokens are not predictable.
security.allow_x_headers bool
Allow the Input class to use "X" headers when present, such as HTTP_X_FORWARDED_FOR or HTTP_X_FORWARDED_PROTO.
security.uri_filter array
What php functions to use to filter the URI.
security.input_filter array
What php functions filter the input arrays ($_GET, $_POST and $_COOKIE). Can be set to xss_clean, this may cause a performance hit based on the size of the input.
security.output_filter array
What php functions filter the variables set to a view. Can be set to xss_clean, this may cause a performance hit based on the size of the variables.
security.auto_filter_output bool
Whether to automatically encode (htmlentities) view data.
security.whitelisted_classes array()
With output encoding switched on all objects passed will be converted to strings or throw exceptions unless they are instances of the classes in this array.
cookie array Array, containing the configuration keys define the global cookie settings:
cookie.expiration int
Number of seconds before the cookie expires.
cookie.path string
Restrict the path that the cookie is available to.
cookie.domain string
Restrict the domain that the cookie is available to. bool
Only transmit cookies over secure connections.
cookie.http_only bool
Only transmit cookies over HTTP, disabling Javascript access.
module_paths array
Paths to module directories. Used when adding a module without specifying the location.
always_load array Array, containing the items the framework has to load when it initializes:
always_load.packages array
Which packages to autoload. Specify like so: array('package') or array('package' => PKGPATH.'path/to/package'). In order for this to work a package path must be set in package_paths
always_load.modules array
Which modules to autoload. Specify like so: array('package'). Autoloaded modules are accessible via the URL. In order for this to work a module path must be set in module_paths
always_load.classes array
Which classes to autoload and initiate. When you want to autoload a class from a package or module, make sure that is autoloaded too!
always_load.config array
Which config files to autoload. Load a config file into a group like so: array('config') or array('filename' => 'group'). If you do not want to load the file into a set the group name to null: array('filename' => null).
always_load.language array
Which language files to autoload. Load a config file into a group like so: array('lang') or array('filename' => 'group'). If you do not want to load the file into a set the group name to null: array('filename' => null).

Interacting with config files/settings is done using the Config class. Config files can also be generated using Oil.