The $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->urlsURL paths to various locations in your system, outlined in detail below this section.
$config->pathsDisk paths to various locations in your system, outlined further down in this page.
$config->ajaxIf the current request is an ajax (asynchronous javascript) request, this is set to true.
$config->httpHostCurrent HTTP host name. You may also specify this manually in your /site/config.php file to override auto-detection.
$config->httpsIf the current request is an HTTPS request, this is set to true.
$config->versionCurrent ProcessWire version string (i.e. "2.1.0")
$config->stylesArray 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->scriptsArray 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->rootURL to your site root (homepage) in ProcessWire.
$config->urls->templatesURL to your site templates directory.
$config->urls->adminURL to your admin control panel.
$config->urls->adminTemplatesURL to ProcessWire's admin templates directory.
$config->urls->modulesURL to ProcessWire's core modules directory.
$config->urls->siteModulesURL to your site modules directory.
$config->urls->coreURL to ProcessWire's core directory.
$config->urls->assetsURL to ProcessWire's assets directory where site-specific files, caches and logs are kept.
$config->urls->filesURL 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->rootPath to your site root directory in ProcessWire.
$config->paths->templatesPath to your site templates directory.
$config->paths->adminTemplatesPath to ProcessWire's admin templates directory.
$config->paths->modulesPath to your core modules directory.
$config->paths->siteModulesPath to your site-specific modules directory.
$config->paths->corePath to ProcessWire's core directory.
$config->paths->assetsPath to ProcessWire's assets directory where site-specific files, caches and logs are kept.
$config->paths->filesPath to ProcessWire's files directory, where page-specific files are kept in page ID numbered directories.
$config->paths->cachePath to ProcessWire's cache directory.
$config->paths->logsPath to ProcessWire's logs directory.
$config->paths->tmpPath to ProcessWire's temporary storage directory.
$config->paths->sessionsPath 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.

Latest news

  • ProcessWire Weekly #553
    In the 553rd issue of ProcessWire Weekly we'll check out the latest weekly update from Ryan, introduce a new third party module called Text Synthesis, and more. Read on!
    Weekly.pw / 14 December 2024
  • Custom Fields Module
    This week we look at a new ProFields module named Custom Fields. This module provides a way to rapidly build out ProcessWire fields that contain any number of subfields/properties within them.
    Blog / 30 August 2024
  • Subscribe to weekly ProcessWire news

“Yesterday I sent the client a short documentation for their ProcessWire-powered website. Today all features already used with no questions. #cmsdoneright—Marc Hinse, Web designer/developer