Configuring your application

Introduction

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 
null
 The base URL of the application. Can be relative. MUST contain a trailing slash. ('/foo/', 'http://example.com/')
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 
'index.php'
 The name of the main bootstrap file. Set this to false or remove if you using mod_rewrite.
controller_prefix string 
'Controller_'
 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 
false
 Whether to enable the profiler.
cache_dir string 
APPPATH.'cache/'
 The directory to store cache files in. This directory must be writable.
caching bool 
false
 Whether to enable file finder caching.
cache_lifetime int 
3600
 The file finder cache lifetime in seconds.
ob_callback callback 
null
 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 
array(
)
 On which php errors to proceed execution. See Error handling.
errors.throttle int 
10
 How many errors to show before we stop showing them. (prevents out-of-memory errors)
errors.notices bool 
true
 Whether to show notices.
language string 
'en'
 The default application language, used by the Lang class.
locale string 
'en_US'
 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 
'UTF-8'
 The application's default character encoding.
server_gmt_offset int 
0
 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 
'UTC'
 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 
Fuel::L_WARNING
 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 
APPPATH.'logs/'
 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 
false
 Whether to auto-check the csrf token. Read more about csrf.
security.csrf_token_key string 
'fuel_csrf_token'
 Which $_POST key to fetch when checking the csrf token.
security.csrf_expiration int 
0
 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 
false
 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 
array('htmlentities')
 What php functions to use to filter the URI.
security.input_filter array 
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 
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 
true
 Whether to automatically encode (htmlentities) view data.
security.whitelisted_classes array() 
array(
'stdClass',
'Fuel\\Core\\View',
'Fuel\\Core\\Presenter',
'Closure'
)
 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 
0
 Number of seconds before the cookie expires.
cookie.path string 
'/'
 Restrict the path that the cookie is available to.
cookie.domain string 
null
 Restrict the domain that the cookie is available to.
cookie.secure bool 
false
 Only transmit cookies over secure connections.
cookie.http_only bool 
false
 Only transmit cookies over HTTP, disabling Javascript access.
module_paths array 
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 
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 
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 
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 
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 
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.