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

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

<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. The rest of this page contains a list of these static configuration options.

Dates and Times

$config->dateFormatDefault 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'.
$config->timezoneCurrent timezone. Must be one of the PHP timezone options. Default value is 'America/New_York'.

Session

$config->sessionNameSession name as used in session cookie. Default is 'wire'.
$config->sessionExpireSecondsHow many seconds of inactivity before session expires. Default is 86400.
$config->sessionChallengeShould login sessions have a challenge key? (for extra security, recommended). Default is true.
$config->sessionFingerprintShould login sessions be tied to IP and user agent? More secure, but will conflict with dynamic IPs. Default is true.

File creation and identification

$config->chmodDirOctal string permissions assigned to directories created by ProcessWire. Default is "0777".
$config->chmodFileOctal string permissions assigned to files created by ProcessWire. Default is "0666".
$config->templateExtensionExpected extension for template files. Default is "php".
$config->uploadUnzipCommandShell 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/
$config->uploadBadExtensionsFile extensions that are always disallowed from uploads. Default is:
php php3 phtml exe cfm shtml asp pl cgi sh vbs jsp

Mode

$config->debugDebug 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. 
$config->advancedTurns on additional options in ProcessWire for use during ProcessWire core and/or module development. Default is false.
$config->demoDemo Mode - Disables save functions in Process admin modules. Default is false.

MySQL Database

$config->dbHostDatabase hostname
$config->dbNameDatabase name
$config->dbUserDatabase user
$config->dbPassPassword for database user
$config->dbPortDatabase port. Default is 3306.
$config->dbCharsetDatabase character set. Default is 'utf8'.
$config->dbSocketOptional 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.

Authentication

$config->userAuthHashTypeHash 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'.
$config->userAuthSaltGenerated automatically at installation time. A random salt string that is used in generating password hashes. A unique account-specific hash is also used.

Pagination

$config->pageNumUrlPrefixPrefix to use in page URLs for page numbers, i.e. a prefix of 'page' would use 'page1', 'page2', etc. Default is 'page'.

E-Mail

$config->adminEmailOptional e-mail address to send fatal error notifications to.

System IDs

$config->adminRootPageIDPage ID of the admin control panel home.
$config->trashPageIDPage ID of the trash page.
$config->loginPageIDPage ID of the admin login page.
$config->http404PageIDPage ID of the 404 page.
$config->usersPageIDPage ID of the users parent page.
$config->rolesPageIDPage ID of the roles parent page.
$config->permissionsPageIDPage ID of the permissions parent page.
$config->guestUserPageIDPage ID of the guest user account.
$config->superUserPageIDPage ID of the superuser account.
$config->guestUserRolePageIDPage ID of the guest role.
$config->superUserRolePageIDPage ID of the superuser role.
$config->userTemplateIDTemplate ID of the system 'user' template.
$config->roleTemplateIDTemplate ID of the system 'role' template.
$config->permissionTemplateIDTemplate 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.

HTTP Hosts 

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

Comments

  • Alan Bristow

    Alan Bristow 6 years ago 33

    Hi,

    Under 'Runtime Configuration' the line that reads:

    $config->httpHost | Current HTTP host name

    If this is used then the host name appears to be duplicated (when echo'd), but it looks OK when the command is:

    $config->urls->httpHost

    I hope that's useful and not me misinterpreting the info :)

    Cheers, -Alan

  • Alan Bristow

    Alan Bristow 6 years ago 22

    UhOh, I think I am misinterpreting, my code is

    Logout

    and it looks like $config is not meant to be echo'd like this (taking on the last echod value), so apologies and ignore my previous comment which I am guessing is wrong, I'll go and teach myself how I ought to do this :)

  • Kristoffer

    Kristoffer 3 years ago 10

    $config->prependTemplateFile = '_header.inc';
    $config->prependTemplateFile = '_init.inc';
    // Whatever file you define there will be automatically included before all of your site template files (except for the one used by the admin).

    $config->appendTemplateFile = '_main.inc';
    $config->appendTemplateFile = '_footer.inc';
    // The specified file is automatically included after your site template files (except for the one used by the admin).

  • EntitySelf

    EntitySelf 8 months ago 10

    There also is a 'new' template file/output strategy you can enable using:

    $config->useMarkupRegions = true;

    https://processwire.com/blog/posts/processwire-3.0.49-introduces-a-new-template-file-strategy/

    It's worth going over the comments in /wire/core/Config.php

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.