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.
profiling bool
false
Whether to enable the profiler.
profiling_paths mixed
array(
	    'APPPATH' => APPPATH,
	    'COREPATH' => COREPATH,
	    'PKGPATH' => PKGPATH,
),
Array of path-to-string translations, to hide the absolute path, and to shorten the path being displayed (for layout purposes).
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, containing the configuration keys to control behaviour when detecting errors:
.continue_on array
array(
)
On which php errors to proceed execution. See Error handling.
.throttle int
10
How many errors to show before we stop showing them. (prevents out-of-memory errors)
.notices bool
true
Whether to show notices.
 
language string
'en'
The default application language, used by the Lang class.
language_fallback string
'en'
This language code will be used when the requested language file doesn't exist in the active language. This should be your main application language.
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
null
The server timezone. If set to null, the timezone configured in your php.ini file will be used.

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_file string
null
The file the log needs to be written to. If not given, a filename will be generated.
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.
cli_backtrace bool
false
If true, a backtrace will be printed when a PHP fatal error is encountered in CLI mode (similar to the html error pages).
security Array, containing the configuration keys to control your application security:
.csrf_autoload bool
false
Whether to auto-check the csrf token. Read more about csrf.
.csrf_autoload_methods array
array(
	'post', 'put', 'delete'
)
List of HTTP methods for which csrf token auto-checking will happen.
.csrf_bad_request_on_fail bool
false
If true, an HttpBadRequestException will be thrown. If false, a SecurityException will be thrown. It is false by default for backward compatibility reasons.
.csrf_auto_token bool
false
If true, a hidden csrf token input field will be automatically added to each form created using Form::open().
.csrf_token_key string
'fuel_csrf_token'
Which $_POST key to fetch when checking the csrf token.
.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.
.csrf_rotate bool
true
If true, the CSRF token is always rotated after token validation, no token will be reused. If false, tokens will be reused until they expire, or until Security::set_token(true) is called to manually rotate it.
.token_salt string
'put your salt value here...'
A salt to make sure the generated security tokens are not predictable.
.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.
.uri_filter array
array('htmlentities')
What php callables to use to filter the URI.
.input_filter array
array()
What php callables to use to filter the input arrays ($_GET, $_POST and $_COOKIE). Can be set to xss_clean, but this may cause a performance hit based on the size of the input.
.output_filter array
array()
What php callables to use to filter the variables set onto a view. Can be set to xss_clean, but this may cause a performance hit based on the size of the variables.
.htmlentities_flags integer
ENT_QUOTES
Whether to automatically encode (htmlentities) view data.
.htmlentities_double_encode bool
false
Whether or not to encode HTML entities as well.
.auto_filter_output bool
true
Whether to automatically encode (htmlentities) view data.
.filter_closures bool
true
If true, closures passed onto Views will be executed, and their return value will be filtered and passed on to the View. If false, the closure itself will be passed to the view.
.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.
.form-double-urlencoded bool
false
Set this to true of your client sends data using the HTTP PUT, DELETE or PATCH methods using the www-form-urlencoded content-type, and it's contents is urlencoded locally before submitting.
.clean_paths mixed
array(
),
Array of path-to-string translations, to hide the absolute path, and to shorten the path being displayed in any output. Note that for security reasons, APPPATH, COREPATH, PKGPATH, and DOCROOT will always be translated.
 
cookie Array, containing the configuration keys to define the global cookie settings:
.expiration int
0
Number of seconds before the cookie expires.
.path string
'/'
Restrict the path that the cookie is available to.
.domain string
null
Restrict the domain that the cookie is available to.
.secure bool
false
Only transmit cookies over secure connections.
.http_only bool
false
Only transmit cookies over HTTP, disabling Javascript access.
 
validation Array, containing the configuration keys to control validation behaviour :
.global_input_fallback bool
true
Whether to fallback to global inout data when a value is not found in the input array passed to validation.
 
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.
routing Array, containing the configuration keys to control routing behaviour :
.case_sensitive bool
true
Whether URI routing is case-sensitive or not. If true, "/THIS" and "/this" are different routes.
.strip_extension mixed
true
If false, nothing will be stripped. If true, all extensions will be stripped. If an array, it should contain a list of extensions (including the leading DOT!) that needs to be stripped.
.module_routes bool
false
When true, the modules routes config file is loaded and added to the global routing table when you load the module.
 
response Array, containing the configuration keys to control response behaviour :
.redirect_with_wildcards bool
true
If true, you can use the "*" as a segement wildcard when redirecting. These segments will then be filled in from the original request URI. So a redirect on "admin/user/edit" to "*/*/view" will redirect to "admin/user/view".
 
config Array, containing the configuration keys to control the configuration environment :
.database string
null
The database that stores your configuration data table, if you have opted to use the database as you configuration data backend.
.table_name string
'config'
The table that stores your configuration data, if you have opted to use the database as you configuration data backend.
.memcached array
array('identifier' => 'config',
	'servers' => array(
		array(
			'host' => '127.0.0.1',
			'port' => 11211,
			'weight' => 100),
	),
)
Memcached configuration, if you have opted to use a memcached store as you configuration data backend.
 
lang Array, containing the configuration keys to control the language environment :
.database string
null
The database that stores your translation data table, if you have opted to use the database as you translation data backend.
.table_name string
'config'
The table that stores your translation data, if you have opted to use the database as you translation data backend.
 
module_paths array
array(APPPATH.'modules'.DS)
Paths to module directories. Used when adding a module without specifying the location.
package_paths array
array(PKGPATH)
Paths to package directories. Used when adding a package without specifying the location.
always_load Array, containing the items the framework has to load when it initializes:
.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
.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
.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!
.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).
.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.