ProcessWire $config API variable

The $config API variable contains all the settings specific to your site 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). See the full $config API reference

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 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.

Runtime Configuration

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->ajax	If the current request is an ajax (asynchronous javascript) request, this is set to true.
$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.
$config->scripts	Array used by ProcessWire admin to keep track of what javascript 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

$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.

Module URLs

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 <head> section:

<link rel='stylesheet' type='text/css' href='<?=$config->urls->templates?>styles/main.css' />

Generate a link to your site's homepage:

<a href='<?=$config->urls->root?>'>Home</a>

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.

$config->paths

$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.

Module Paths

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 = $template->name . ".css";
if(is_file($config->paths->templates . "styles/$cssFile")) {
  echo "<link rel='stylesheet' type='text/css' href='{$config->urls->templates}styles/$cssFile' />";
}
$jsFile = $template->name . ".js";
if(is_file($config->paths->templates . "scripts/$jsFile")) {
  echo "<script type='text/javascript' src='{$config->urls->templates}scripts/$jsFile'></script>";
}

Static Configuration

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.

$config->httpHosts

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.

The $config API variable