Support

Documentation

WordPress and the wp-config.php file

[Note]Note

is section is only applicable to Akeeba Backup for WordPress.

Overview

Akeeba Backup for WordPress offers several different methods for automating your backups. All of these run outside of WordPress itself, i.e. WordPress the CMS is not being loaded when you are taking a backup or checking the status of the last backup. This is intentional; WordPress was not created with automation in mind. However, we do need access to WordPress' configuration to take a backup or check on its status.

By default, you just need to visit Akeeba Backup for WordPress' control panel page once after installing it, after changing your database connection information or after transferring your site to a new server. Akeeba Backup will automatically pick up the new database connection information from WordPress and create the file wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php. This file is then used by all automation methods to connect to WordPress' database.

That is to say, in most cases you do not need to do anything. Akeeba Backup does everything for you behind the scenes.

When do I need to troubleshoot?

In rare cases the automatic backups will fail with an error about not being able to connect to the database or a PHP Fatal Error indicating the file that triggered it was awf://abwp/wp-config.php. This is when you need to make a manual intervention.

This is more likely to happen when transferring a file to a new server than when installing Akeeba Backup for the first time on a site.

What should I do?

First try deleting the file wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php and visit Akeeba Backup's Control Panel page. Check that the file wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php has been created afresh. If the file is there you can stop reading.

If the file has not been created set the permissions of the wp-content/plugins/akeebabackupwp/helpers/private folder to 0777. Visit Akeeba Backup's Control Panel page. Check that the file wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php has been created afresh. Now set the permissions of the wp-content/plugins/akeebabackupwp/helpers/private folder to 0755 for security reasons. If the file is there you can stop reading.

While this solves the issue for the majority of sites, there might be some rare cases this may still not work. For example, your host may not be allowing you to change the permissions on that folder to 0777. In this case check whether your automatic backups work after deleting the file wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php. If they do, you're done and you can stop reading now.

If your automated backups still don't work create an empty text file on your computer and name it no-wp-config.txt. Upload this file in the folder wp-content/plugins/akeebabackupwp/helpers/private of your site. This tells Akeeba Backup to use an alternative method for reading WordPress' configuration.

If even after that your automated backups still don't work you will have to do this the hard way.

Create a new file called wp-config.php in a text editor and add the following contents:

<?php
global $table_prefix;
$table_prefix = 'wp_';
define('DB_NAME', 'wordpress');
define('DB_USER', 'wordpress');
define('DB_PASSWORD', 'wordpress');
define('DB_HOST', '127.0.0.1');

You will need to change the lines in the file above to match your site's database configuration. If you are not sure you can either ask your host or check the contents of the wp-config.php file in your site's root.

Upload the wp-config.php file you created in the folder wp-content/plugins/akeebabackupwp/helpers/private of your site.

Technical information

All automation methods in Akeeba Backup for WordPress run outside WordPress itself. This prevents third party themes and plugins from interfering with the backup, making the backup process faster and more reliable. It also allows Akeeba Backup Professional to offer CLI scripts for CRON jobs, something that WordPress cannot do without also installing WP-CLI.

In any case, running outside of WordPress the automated backup scripts still need to read WordPress' configuration to figure out how to connect to the database of your WordPress site. This is necessary not just for backing up the database but also for loading Akeeba Backup's configuration and the list of past and running backups used when checking the latest backup status.

Unlike other CMS, WordPress configuration file (wp-config.php) cannot be included directly. It is written in such a way that it tries to load too much of the WordPress CMS, including third party mu-plugins which may assume that they are running inside a WordPress request – something which is not true for Akeeba Backup's automations.

In fact, WordPress configuration file is written in such a way that even WP-CLI itself – written and supported by core WordPress developers – has even more caveats than Akeeba Backup with regards to reading the WordPress configuration! To make this crystal clear, the WordPress core developers admit through their code that WordPress' configuration is not implemented with automation in mind, they have to work around their own software.

In any case, the configuration conundrum can be solved in three different ways:

  1. Separate configuration. Create a configuration file just for our software running outside of WordPress. This is essentially what WP-CLI does when you give it command line parameters or create a configuration file for it.

  2. File inclusion. Try to sanitize the wp-config.php file to remove its last line which loads too much of the WordPress CMS. The result can be run through PHP. This is what WordPress' WP-CLI command line tool does.

  3. Configuration extraction. Use regular expressions to extract the values of the constants defined in wp-config.php. This is what we did in Akeeba Backup for WordPress 1.0.0 to 7.2.2 inclusive.

By default, Akeeba Backup for WordPress uses the first method. Instead of asking you to provide the configuration file yourself it automatically creates that file (wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php) when you visit its Control Panel page. This works fine on most hosts. If your host has set up PHP in such a way that it cannot write to that file Akeeba Backup for WordPress falls back to the second method.

The second is very similar to how WordPress' own WP-CLI command line tool works. It reads the site's wp-config.php file and removes the final require_once line which is what loads more of the WordPress CMS than its configuration – the reason why, unlike other CMS, WordPress' configuration file cannot be included directly by third party software running outside of it. This method is susceptible to breaking with a PHP Fatal Error in some cases, e.g. if the wp-config.php file was written in a way that tries to include other files using relative paths or depends on system environment variables which are only present in an HTTP request (when accessing WordPress over the web). Do remember that on those sites even WP-CLI won't work without manual configuration, i.e. it's not a problem with Akeeba Backup but a problem with how the wp-config.php file was implemented in a non-standard way.

The third method is a safer alternative to the first, in the sense that it is not susceptible to breaking with a PHP Fatal Error. However, if your wp-config.php file contains multiple configurations – such as for a live and a staging site – the order they are present in the file may confuse the detection code and cause Akeeba Backup to pick up the wrong set of configuration variables. This is what we were using up to an including Akeeba Backup for WordPress 7.2.2. On some sites this method may work better than the second one. You can enable it by creating an empty text file wp-content/plugins/akeebabackupwp/helpers/private/no-wp-config.txt.

Here is the way these methods work in Akeeba Backup.

If the file wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php is present. Akeeba Backup will use the Configuration Extraction method to determine an initial configuration. It will then perform the Separate Configuration method, i.e. any configuration values present in the wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php file will override any values extracted from the site's main wp-config.php file. This is the only case where two methods are used at the same time. This is on purpose and prevents a partial configuration from triggering a hard to troubleshoot failure mode.

If the file wp-content/plugins/akeebabackupwp/helpers/private/wp-config.php is missing but the file wp-content/plugins/akeebabackupwp/helpers/private/no-wp-config.txt is present. Akeeba Backup will use the Configuration Extraction method to determine the configuration.

If neither file is present Akeeba Backup will use the File Inclusion method.