What role does Joomla’s configuration.php file play?

A Joomla installation contains a great deal of files and folders. Many of these are ‘behind the scenes’ and you’re unlikely to ever interact with them, however one file worth getting acquainted with and understanding is Joomla’s main configuration file. In this article we’ll answer the most common questions about Joomla’s central configuration file, configuration.php, along with some helpful tips.

  • Introducing Joomla’s central configuration file

    The file /configuration.php is one of the most important files on your Joomla site.

    This file contains the most important site settings, such as the name of your site and your database login details. Without this file, your Joomla site cannot function.

    The file is generated during the initial installation of your site and the default values generated typically require no further changes.

    However, sooner or later you might need to change some of the values stored here, so we suggest you read on to understand the basics of how this file works.

    Will I need to modify the configuration.php file directly?

    Many of the values stored within configuration.php can be edited via the Global Configuration panel within the administration section of your Joomla site.

    Changes made to those settings through the Joomla backend will be automatically and immediately saved in your configuration.php file, without the need to modify the file directly.

    Image of Global configuration tab inside Joomla administrator.
    Global Configuration

    However, in certain cases you might need to edit the file directly:

    1. Some settings are not available through the Global Configuration, in which case direct modification of the file is necessary.
    2. If your Joomla site crashes, a manual change to configuration.php (e.g. to reconnect the site with your database) might be necessary to get things back on track.
    3. If you’re working on your site locally, you might need to change certain values within configuration.php before moving the site to your web server.

    Where can I find configuration.php?

    Before we can open/edit the file, we need to know where to find it!

    This part couldn’t be easier: the configuration.php file is located in the root of your Joomla installation.

    Image of the root folder with an arrow pointing to configuration.php file.
    Location of the configuration.php file within the Joomla folder structure

    The easiest way to access configuration.php file (and any other file) is by connecting to your server via FTP. Check out our article on accessing your Joomla site with FTP for a quick guide on how to get started.

    Which values are most often changed?

    Before making any modifications to this most important of files, make a backup.

    To do so, simply copy the original configuration.php file to a directory somewhere on your local computer. In case you encounter any problems, you can quickly and easily drag it back to restore the original file.

    When you open the file, it’s easy to get overwhelmed with the amount of available settings. Fortunately, in most cases you’ll be changing only a few of these.

    Here are most commonly changed settings and a short description of each:

    • $offline
      This option allows you to temporarily put your Joomla website offline, e.g. in case of maintenance. The values are as follows: ‘0’ – site online, ‘1’ – site offline
    • $offline_message
      In case $offline is set to ‘1’ this is the message that will be shown to the user.
    • $sitename
      The name of your site, typically used in the browser title field.
    • $list_limit
      The default number of results to display in lists in the Joomla backend.
    • $debug
      The value ‘1’ turns debugging mode on, which will display any errors at the bottom of the page in the frontend. Should be set to ‘0’ on live websites.
    • $host
      The database host that Joomla should connect to. In most cases, this will be simply ‘localhost’, which indicated that the Joomla database is stored on the same server as the Joomla installation directory.
    • $user
      The username for connecting to your Joomla database.
    • $password
      The password for connecting to your Joomla database.
    • $db
      The name of the database that Joomla should connect to.
    • $live_site
      The URL of your Joomla site.
    • $error_reporting
      The level of error reporting.
      • ‘default’ or -1: uses defaults from php.ini file
      • ‘none’ or 0: disables error reporting, should be set on live websites
      • ‘simple’: enables display_errors, only displays E_ERROR, E_WARNING and E_PARSE
      • ‘maximum’: enables display_errors, displays E_ALL
      • ‘development’: enables display_errors, displays all error messages
    • $log_path
      The path where the logs are stored. Log is a folder where Joomla stores files containing reports about your website.
    • $tmp_path
      The path where Joomla stores temporary files. Once common usage of this directory is to store files when installing a new extension.
    • $caching
      ‘0’ is off, ‘1’ is Conservative, ‘2’ is Progressive

    Learn more about caching by reading How to clear the cache in Joomla.

    Final words and warnings

    Before making any modifications on your site, it’s advisable to make a backup.

    Read about how to make a backup of your Joomla site.

    If you know that you are only modifying configuration.php, make a backup of the file before making any changes. Copy the original to a directory somewhere on your local computer and be careful. One simple character out of place could break your whole website…

    Jigsaw Puzzle on the table.

    If you’ve managed to do the above on your site, and are out of ideas, don’t fret!
    We’re a Joomla agency that gains endless pleasure from finding and fixing bugs and errors … in configuration.php and elsewhere, and will be happy to help. Contact us and we’ll get back to you as soon as possible!

    Further Insights