Configuration - General - FuelPHP Documentation

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`	If true, PHP notices are shown inline. If false, an E_USER_NOTICE exception is thrown.

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 \| array	`'en_US'`	Used for set the locale for your application, if it differs from the default server or PHP configuation locale. See setlocale() for more information. The syntax setting for this can differ per OS, Ubuntu for example requires a `.utf8` (the encoding) suffix.. To pass multiple options, pass an indexed array with the locales in order of preference. If you don't need to use a difffent locale, set to `false`.
locale_category	int \| array	`LC_ALL`	One or more categories for which the defined locale should be set, define either a single category, like the LC_ALL constant, or an indexed array of LC constants. The array is needed because unlike other constants in PHP, these can't be or'd.
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.
.recursive	bool	`false`	If true, and the requested URI resolves to a defined route, but that route doesn't resolve to a valid controller action, the resolved route will be processed again by the routing engine.

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.