$config API variable contains all the settings specific to your site’s configuration.
This includes URLs and paths, database configuration, session configuration, and more.
ProcessWire automatically populates several entries into $config and then includes your site-specific entries stored in /site/config.php. These configuration options are made available to your site templates in the $config API variable. This page serves as a reference for all of the information you can access from $config. It also covers where these settings come from, how you can modify them, and how you can add more (should it suit your needs).
Where the $config settings come from
- Runtime configuration
ProcessWire populates several configuration settings at runtime on each request. This includes URLs, paths and information about the request.
- Static site configuration file: /site/config.php
This file contains your site-specific configuration options and is not overwritten during upgrades. You may modify settings in this file or add additional settings as needed.
- Static system configuration file: /wire/config.php (ProcessWire 2.1+ only)
ProcessWire sets some default configuration options in this file. You should not edit this file directly since it will be overwritten during upgrades. If needed, you can override any of these items by specifying them in /site/config.php.
ProcessWire sets several $config variables at runtime and these do not appear in the configuration files. Below is a list of these variables.
|$config->urls||URL paths to various locations in your system, outlined in detail below this section.|
|$config->paths||Disk paths to various locations in your system, outlined further down in this page.|
|Current HTTP host name. You may also specify this manually in your /site/config.php file to override auto-detection.|
|If the current request is an HTTPS request, this is set to true.|
|Current ProcessWire version string (i.e. "2.1.0")|
|Array used by ProcessWire admin to keep track of what stylesheet files it's template should load. It will be blank otherwise. Feel free to use it for the same purpose in your own sites.|
Runtime Configuration: URLs
Items from $config->urls reflect the http path one would use to load a given location in the web browser. Items retrieved from $config->urls always end with a trailing slash. Please note that only the first two items from this list are likely to be useful in typical site development, whereas the others may have use in module development.
|URL to your site root (homepage) in ProcessWire.|
|URL to your site templates directory.|
|URL to your admin control panel.|
|URL to ProcessWire's admin templates directory.|
|URL to ProcessWire's core modules directory.|
|URL to your site modules directory.|
|URL to ProcessWire's core directory.|
|URL to ProcessWire's assets directory where site-specific files, caches and logs are kept.|
|URL to ProcessWire's files directory, where page-specific files are kept in page ID numbered directories.|
In addition to the URLs mentioned above, you can retrieve the URL to any given module by requesting it from $config->urls->moduleName, i.e.
<?php // gives a URL to Apeisa's AdminBar module, i.e. /site/modules/AdminBar/ echo $config->urls->AdminBar;
Examples of how you might use $config->urls in your site templates:
Generate a stylesheet link in your document's <head> section:
<link rel='stylesheet' type='text/css' href='<?=$config->urls->templates?>styles/main.css' />
Generate a link to your site's homepage:
Runtime Configuration: Paths
All of what can be accessed from $config->urls can also be accessed from $config->paths, with one important difference: the returned value is the full disk path on the server. There are also a few items in $config->paths that aren't in $config->urls. All entries in $config->paths always end with a trailing slash. Note that there is a good chance you won't be using $config->paths in your regular site development tasks, so you may skip this section if it isn't applicable to you.
|Path to your site root directory in ProcessWire.|
|Path to your site templates directory.|
|Path to ProcessWire's admin templates directory.|
|Path to your core modules directory.|
|Path to your site-specific modules directory.|
|Path to ProcessWire's core directory.|
|Path to ProcessWire's assets directory where site-specific files, caches and logs are kept.|
|Path to ProcessWire's files directory, where page-specific files are kept in page ID numbered directories.|
|Path to ProcessWire's cache directory.|
|Path to ProcessWire's logs directory.|
|$config->paths->tmp||Path to ProcessWire's temporary storage directory.|
|Path to ProcessWire's session storage directory.|
In addition to the paths mentioned above, you can retrieve the disk path to any given module by requesting it from $config->path->moduleName, i.e.
<?php // gives a disk path to Apeisa's AdminBar module, i.e. /var/www/site/modules/ echo $config->paths->AdminBar;
Example of how you might use $config->paths in your site templates:
Create links to JS and CSS files with the same name as the current page's template, but only if they actually exist on the disk:
<?php $cssFile =
Static configuration options are defined as those that have their value set in a configuration file. Unlike runtime configuration options, you can modify the value of a static configuration option by editing /site/config.php. The rest of this page contains a list of these static configuration options.
Dates and Times
|Default system date format as used by ProcessWire admin. Preferably in a format that is string sortable. This should be a PHP date() string. Default value is 'Y-m-d H:i:s'.|
|Current timezone. Must be one of the PHP timezone options. Default value is 'America/New_York'.|
|Session name as used in session cookie. Default is 'wire'.|
|How many seconds of inactivity before session expires. Default is 86400.|
|Should login sessions have a challenge key? (for extra security, recommended). Default is true.|
|Should login sessions be tied to IP and user agent? More secure, but will conflict with dynamic IPs. Default is true.|
File creation and identification
|Octal string permissions assigned to directories created by ProcessWire. Default is "0777".|
|Octal string permissions assigned to files created by ProcessWire. Default is "0666".|
|Expected extension for template files. Default is "php".|
|Shell command to unzip archives, used by WireUpload class. If unzip doesn't work, you may need to precede 'unzip' with a path. Default is: |
unzip -j -qq -n /src/ -x __MACOSX .* -d /dst/
|File extensions that are always disallowed from uploads. Default is:|
php php3 phtml exe cfm shtml asp pl cgi sh vbs jsp
|Debug mode causes additional info to appear for use during dev and debugging. Set this to true temporarily if you get a blank screen or untelligible error. Do not leave this set at true with a live site. Default is false.|
|Turns on additional options in ProcessWire for use during ProcessWire core and/or module development. Default is false.|
|Demo Mode - Disables save functions in Process admin modules. Default is false.|
|Password for database user|
|Database port. Default is 3306.|
|Database character set. Default is 'utf8'.|
|Optional DB socket config for sites that need it (for most you should exclude this).|
The MySQL database configuration options are set automatically at installation time. The values are saved in /site/config.php.
|Hash method to use for passwords. typically 'md5' or 'sha1'. Can be any available with your PHP's hash() installation. For instance, you may prefer to use something like sha256 if supported by your PHP installation. Default is 'sha1'.|
|Generated automatically at installation time. A random salt string that is used in generating password hashes. A unique account-specific hash is also used.|
|Prefix to use in page URLs for page numbers, i.e. a prefix of 'page' would use 'page1', 'page2', etc. Default is 'page'.|
|Optional e-mail address to send fatal error notifications to.|
|Page ID of the admin control panel home.|
|Page ID of the trash page.|
|Page ID of the admin login page.|
|Page ID of the 404 page.|
|Page ID of the users parent page.|
|Page ID of the roles parent page.|
|Page ID of the permissions parent page.|
|Page ID of the guest user account.|
|Page ID of the superuser account.|
|Page ID of the guest role.|
|Page ID of the superuser role.|
|Template ID of the system 'user' template.|
|Template ID of the system 'role' template.|
|Template ID of the system 'permission' template.|
These system IDs are located in the /wire/config.php file, and may be overridden in /site/config.php. However, we don't recommend making changes to these.
|$config->httpHosts||Array of allowed host names.|
This requirement was added in ProcessWire 2.4. It is added by the installer and contains an array of all host names your site will run from. If you migrate your site from one server to another (or from localhost to a production server), you will want to update this with the new host name(s) in your /site/config.php file. For example, the httpHosts for this site (processwire.com) looks like this:
$config->httpHosts = array( 'processwire.com', // our primary hostname 'www.processwire.com', // alternate hostname 'dev.processwire.com', // staging server 'localhost:8888' // MAMP local dev server );
Adding your own configuration options
You can add any of your own configuration options to your /site/config.php file and they will be available in the $config API variable to all of your templates. For example, lets say that we wanted to keep our thumbnail image width and height in our configuration file for use by our templates. We would add something like the following to our /site/config.php:
<?php $config->thumbWidth = 200; $config->thumbHeight = 150;
Then any of your template files could access those configuration options as easily as this:
<?php $thumb = $page->image->size($config->thumbWidth, $config->thumbHeight);
Maintaining a separate development configuration file
You may optionally maintain a separate development configuration file at /site/config-dev.php. When present, ProcessWire will use this file rather than /site/config.php. This may be useful on your development and/or staging server and allows you to maintain the same /site/config.php file between staging and production server. As an example, your /site/config-dev.php file may have the database connection information specific to your development server, while your /site/config.php has the database connection information specific to your production server. This prevents the possibility of overwriting your production server's configuration file during migrations and mirrors. Of course, you will want to ensure that your config-dev.php file does not end up on your production server by adding it to the file exclusion list of whatever tool you are using to transfer files.
Your e-mail is kept confidential and not included with your comment. Website is optional.