The $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 an introduction to $config and 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
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 sets all default configuration options in this file. As a result, it is a good reference of all available $config options and default values. 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.|
|$config->httpHost||Current HTTP host name. You may also specify this manually in your /site/config.php file to override auto-detection.|
|$config->https||If the current request is an HTTPS request, this is set to true.|
|$config->version||Current ProcessWire version string (i.e. "2.1.0")|
|$config->styles||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.
|$config->urls->root||URL to your site root (homepage) in ProcessWire.|
|$config->urls->templates||URL to your site templates directory.|
|$config->urls->admin||URL to your admin control panel.|
|$config->urls->adminTemplates||URL to ProcessWire's admin templates directory.|
|$config->urls->modules||URL to ProcessWire's core modules directory.|
|$config->urls->siteModules||URL to your site modules directory.|
|$config->urls->core||URL to ProcessWire's core directory.|
|$config->urls->assets||URL to ProcessWire's assets directory where site-specific files, caches and logs are kept.|
|$config->urls->files||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 ProcessHannaCode /site/modules/ProcessHannaCode/ echo $config->urls('ProcessHannaCode');
Examples of how you might use $config->urls in your site templates:
Generate a stylesheet link in your document's
<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.
|$config->paths->root||Path to your site root directory in ProcessWire.|
|$config->paths->templates||Path to your site templates directory.|
|$config->paths->adminTemplates||Path to ProcessWire's admin templates directory.|
|$config->paths->modules||Path to your core modules directory.|
|$config->paths->siteModules||Path to your site-specific modules directory.|
|$config->paths->core||Path to ProcessWire's core directory.|
|$config->paths->assets||Path to ProcessWire's assets directory where site-specific files, caches and logs are kept.|
|$config->paths->files||Path to ProcessWire's files directory, where page-specific files are kept in page ID numbered directories.|
|$config->paths->cache||Path to ProcessWire's cache directory.|
|$config->paths->logs||Path to ProcessWire's logs directory.|
|$config->paths->tmp||Path to ProcessWire's temporary storage directory.|
|$config->paths->sessions||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:
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. See the full $config API reference for more details on all the available properties.
The $config->httpHosts property (an array) 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:
$config->thumbWidth = 200; $config->thumbHeight = 150;
Then any of your template files could access those configuration options as easily as this:
$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.